MobileChart

Matching the features available for iOS, MobileChart lets you create a wide variety of charts to show in your Android app.

MobileColorPicker

This new control, as its name suggests, lets you use the system color picker to select a color.

MobilePDFViewer

Last year Android added PDFDocument support for creating your own PDFs, and now we’ve added MobilePDFViewer to give you an easy way to show PDF document files from your Android apps.

Zip/Unzip

The FolderItem class now supports the Zip and Unzip methods to make it simple to compress and uncompressed Zip files.

Android Keeps Getting Better

There are also improvements to MobileTabPanel, MobileTextArea, MobileSlider, MobileScrollableArea, Barcode and more. With each release, Android gets closer to feature parity with iOS!

And of course, we continue to squash framework and compiler bugs.

Be sure to check out the full release notes for all the details!

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

What this project includes

• A DesktopWindow (wMain) that provides a clean user interface for selecting an image, inputting your message, and generating the final PDF postcard.
• Intelligent image handling that supports common formats like JPG, PNG, and GIF. The application automatically crops your selected image to a perfect 4:6 aspect ratio, ensuring it fits the postcard layout beautifully.
• Robust PDF generation, leveraging Xojo’s PDFDocument and Graphics classes to embed images and render styled text effectively onto the document.
• Customizable message rendering, which includes a subtle drop shadow effect for improved readability and a polished look against your background image.
• Automated saving of the generated PDF postcard to your desktop, complete with a unique, timestamped filename, and immediate opening of the file in your system’s default viewer for quick review.

Download

You can download the entire Xojo project from GitHub.

This project illustrates Xojo’s robust capabilities for handling graphics and generating PDFs, demonstrating how straightforward it is to create functional and creative desktop applications. We encourage you to use this postcard generator as a springboard for your own ideas. Perhaps you could expand it by adding features like custom fonts, multiple message fields, or even integration with a data source for personalized bulk postcards. Or, consider how Xojo’s PDF features could power entirely new applications for reporting, invoicing, or custom document creation. We’d love to see what you build!

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Year of Code Project

• Year of Code: Kickoff
• January Project: Desktop Apps | Forum Discussion
• February Project: Database Apps | Forum Discussion
• March Project: Web Apps | Forum Discussion
• April Project: User Interface | Forum Discussion
• May Project: Mobile Apps | Forum Discussion
• June Project: Code Sharing | Forum Discussion
• July Project: Charting | Forum Discussion
• August Project: Console Apps | Forum Discussion
• September Project: Games | Forum Discussion
• October Project: Multi-Platform | Forum Discussion
• November Project: PDF | Forum Discussion

How to Play:

Each month we’ll announce a new theme and share an example project of our own. Share your projects to the Xojo Forum thread for that month via GitHub (all the links you need are posted above ↑ ). Learn how to use Xojo and GitHub.

The Prizes:

Monthly winners get $100 at the Xojo store. Every month you submit a project is another chance to win the grand prize. The grand prize is $250 cash plus a Xojo Pro license and a year of GraffitiSuite and will be announce in December. Learn more about the prizes.

The trick is to handle the data coming from any source with the right data structure, for example, an Array. This example uses a plain text file with several lines and columns separated by the Tab character as the source of the data.

In order to follow this tutorial, download the example project.

Getting the Data

As you can see in the example project, the text file has been added to the project using a Build > Copy Files Step (the file name is “Data.txt”), so it is copied to the Resources folder of the compiled app and available for both debugging and release builds.

Then, in the Pressed event of the Button1 control placed on the default Window1, we will access the contents of the file in order to store each of the lines in the Data Array of strings:

Var f As FolderItem = SpecialFolder.Resource("data.txt")
If f <> Nil And f.Exists Then
  Var tis As TextInputStream = TextInputStream.Open(f)
  Var s As String = tis.ReadAll
  data = s.ToArray(EndOfLine.macOS)
End If

PDFRenderer Subclass

The next step is to create a custom class that will implement the methods provided by the PDFTableDataSource Class Interface. We will name the class “PDFRenderer”. Then, from the Inspector Panel, click on the Interfaces button, check the PDFTableDataSource interface and confirm the selection.

Once done, the methods from the class interface will be automatically added to the class:

• AddNewRow
• Completed
• HeaderHeight
• MergeCellsForRow
• PaintCell
• PaintHeaderContent
• RowHeight

Over these we will add three more methods:

The class Constructor:

Public Sub Constructor(document As PDFDocument)
  // Simple constructor… just assign the received object
  // to the "Document" property
  
  Self.document = document
  proxy = New Picture(document.Graphics.Width, document.Graphics.Height)
End Sub

Assign the received PDFDocument instance to the document property. It also creates a graphics instance that will be used as a proxy for calculating the height of the processed text from the data (that won’t be necessary starting with Xojo 2024r4 where some PDFDocument bugs related with that are already fixed).

DrawTable:

This method is the one that will be called to start drawing the table. It will initialize some properties from the received Data (yeah, you can see a property named as “DrawingFromRowSet”, but I left that one on purpose because this project is based on the one dealing with the data coming from a RowSet, so you can see how similar all the process is):

Public Sub DrawTable(data() As String, headers() As String)
  // This is the method we call on the Class to draw
  // a table on a PDFDocument based on an Array of Strings
  
  If document <> Nil And data.LastIndex <> -1 Then
    
    // Assign the received Array to the "Data" property
    Self.data = data
    
    // Assign the received headers to the "Headers" property
    Self.Headers = Headers
    
    // Hey! We are going to create a table from an Array
    // so we use a Boolean property as a flag for that
    // (Yeah, we can do it using other techniques, but this
    // is easy enough for this purpose… while leave this
    // helper class "open" enough for drawing tables based on other
    // data sources).
    Self.DrawingFromRowSet = True
    
    // How many columns are we going to draw?
    // Well… as many as columns (TABs) in any of the Array items (for example, the first one).
    Var totalColumns As Integer = data(0).CountFields(Chr(9))
    
    // This is going to be the "drawable area" on the page
    // for the table = total page width less the left and right margins
    Var totalWidth As Double = document.Graphics.Width - 40 // 40 = 20 points left/right margins
    
    // Creating the PDFTable object here!
    Var table As New PDFTable
    
    // We want to repeat the headers on every page
    table.HasRepeatingHeader = True
    
    // Setting the column count for the table
    table.ColumnCount = totalColumns
    
    // …and the width for every column.
    table.ColumnWidths = CalculateColumnWidths(totalWidth, totalColumns)
    
    // The object from this class will be the responsible
    // of handling all the methods associated with the
    // PDFTableDataSouce Class Interface
    table.DataSource = Self
    
    // Setting the Top and Bottom margins for the drawing
    // of the table on every PDF page
    table.TopMargin = 20
    table.BottomMargin = 20
    
    // …and finally we instruct the PDFDocument object
    // to draw the table!
    document.AddTable(table, 20, 0)
    
    // Lastly, clearing the flag
    Self.DrawingFromRowSet = False
    
  End If
End Sub

CalculateColumnWidths Method

This one will calculate the widths for each column to be rendered in the final PDF document.

Protected Function CalculateColumnWidths(TotalWidth As Double, NumberOfColumns As Double) As String
  // Helper method to get a string for the column widths
  
  ColumnWidth = TotalWidth / NumberOfColumns
  Var s() As String
  
  For n As Integer = 0 To NumberOfColumns - 1
    s.Add(Str(ColumnWidth))
  Next
  
  Return String.FromArray(s, ",")
End Function

Class Properties

Because we need to track things like what the current row or column is to be rendered, the headers, etc., our class needs to add some properties:

• Protected Property ColumnWidth As Integer
• Public Property CurrentColumn As Integer
• Protected Property CurrentHeight As Integer
• Protected Property CurrentRow As Integer
• Protected Property data() As String
• Protected Property document As PDFDocument
• Protected Property DrawingFromRowSet As Boolean
• Public Property Headers() As String
• Protected Property LastRow As Integer
• Protected Property proxy As Picture

PDFTableDataSouce Methods

Time to visit the methods added by the PDFTableDataSouce class interface. These are the methods called by the PDFTable object each time it needs to retrieve a piece of information during the rendering on the PDFDocument, as for example if it needs to add a new row, the height for the Header or the current row… and the painting of the row itself!

AddNewRow Method

This one is called by the PDFTable object in order to know if it needs to render a new row in the table:

Protected Function AddNewRow(rowCount As Integer) As Boolean
  // Part of the PDFTableDataSource interface.
  
  If DrawingFromRowSet And data.LastIndex <> -1 then
    
    // We are going to draw as many rows as rows are in the
    // "data" array
    Return rowCount <= data.LastIndex
    
  End If
End Function

Completed method

This is the method invoked by the PDFTable object when it finished drawing the table, so it is your chance to take additional operations, for example, numbering every page of the PDFDocument (we can’t anticipate that before drawing the table itself):

Protected Sub Completed(x As Double, y As Double)
  // Part of the PDFTableDataSource interface.
  
  // This method is called once the table has been drawed
  // so let's "print" the page number on every page
  // of the PDF Document
  
  Static pageNumber As String = "Page: "
  
  If document <> Nil Then
    Var g As Graphics = document.Graphics
    
    For n As Integer = 1 To document.PageCount
      document.CurrentPage = n
      g.DrawText(pageNumber + Str(n), g.Width - g.TextWidth(pageNumber + Str(n)) - 20, g.Height - g.FontAscent)
    Next
    
  End If
End Sub

HeaderHeight Method

This is the method called by the PDFTable object the returns the height we want to use for rendering the header on the first page and, optionally, on every new page required (added to the document) by rendering the table. In this case we will return a fixed value:

Protected Function HeaderHeight() As Double
  // Part of the PDFTableDataSource interface.
  
  // Returning a fixed height value for the headers
  Return 20
End Function

MergeCellsForRow Method

The PDFTableDataSouce class interface also has the ability to merge cells in the current row, so you can create more elaborated tables. We are not going to use that feature in this example project so it will be empty, no code to be executed.

PaintHeaderContent Method

This is the method in charge of rendering the header for the table, so it receives its own Graphic context with the provided height from the HeaderHeight method and the width calculated from the total of columns (headers) needed to be rendered:

Protected Sub PaintHeaderContent(g As Graphics, column As Integer)
  // Part of the PDFTableDataSource interface.
  
  // Painting the headers for the table
  If column <= Self.Headers.LastIndex Then
    
    Var s As String = headers(column)
    g.DrawingColor = Color.Black
    g.FillRectangle(0, 0, g.Width, g.Height)
    g.DrawingColor = Color.White
    g.DrawText(s, g.Width / 2 - g.TextWidth(headers(column)) / 2, g.Height / 2 + g.FontAscent / 2)
    
  End If
End Sub

RowHeight Method

As the class interface provides a method so we can provide the height for the header, we also have a RowHeight method that the PDFTable object will call before it calls the method in charge of doing the row drawing itself. That way we can have rows of different height based on the height of the own text to be rendered!

Protected Function RowHeight() As Double
  // Part of the PDFTableDataSource interface.
  
  // We need to calculate the height for every row in the Table
  // so let's calculate that based on the taller of the texts (columns)
  // based on text wrapping
  
  If CurrentRow <= data.LastIndex Then
    CurrentHeight = 0
    Var s() As String = data(CurrentRow).Split(Chr(9))
    Var g As Graphics = proxy.Graphics
    Var itemHeight As Integer
    For Each item As String In s
      itemHeight = g.TextHeight(item, ColumnWidth - 40)
      If itemHeight > CurrentHeight Then
        CurrentHeight = itemHeight
      End If
    Next
    
    CurrentRow = CurrentRow  + 1 
    
    Return CurrentHeight + 20
  End If
End Function

PaintCell Method

Lastly, this is the method called by the PDFTable object when it is time to render a given cell for the current row in the table. It receives as parameters both a graphic context with the width and height already suited for the data to be rendered, and also the row and column values so you can get the appropriate data for a given cell from the data source:

Protected Sub PaintCell(g As Graphics, row As Integer, column As Integer)
  // Part of the PDFTableDataSource interface.
  
  // Here is where we really do the drawing
  // the received "g" parameter is for a particula table cell
  // based on the row / column parameters
  // so the origin for X/Y coordinates is at 0,0
  
  If DrawingFromRowSet And data.LastIndex >= row Then
    // Drawing the outer rectangle for the cell
    g.DrawRectangle(0, 0, g.Width, g.Height)
    
    // retrieving the text to be drawn from the Array,
    // using the row and column parameters for that.
    Var s As String = data(row).NthField(Chr(9), column + 1)
    
    // Centering vertically the text on the table cell
    // while the X offset is fixed at 5 points.
    g.DrawText(s, 5, g.Height / 2 + g.FontAscent / 2, ColumnWidth - 20)
    
    // Let's keep track of the last row drawed
    LastRow = row
    
  End If
End Sub

Time to push the Start button!

Everything is setup now in our PDFRenderer class, so let’s get back to the Pressed event of the Button1 control on the default Window1 window. You will remember from the beginning of this tutorial that this is the place where we retrieved the data from the text file. So let’s add the code to create a PDFDocument instance, a new PDFRenderer instance and do the rendering of the table itself from the data:

If data.LastIndex <> -1 Then
  
  // Creating a new PDFDocument Instance
  Var d As New PDFDocument
  
  // Creating the PDFTable renderer helper object (we pass the PDFDocument object to it in the Constructor)
  Var PDFRender As New PDFRenderer(d)
  
  // These will be the headers drawed in the Table
  Var headers() As String = Array("Name", "Surname", "Address", "City", "Email")
  
  // And let's instruct the PDFTable renderer helper to draw the table
  // based in the SQLite database rowset we got in the previous step
  PDFRender.DrawTable(data, headers)
  
  // …and save the resulting PDF File to the Desktop
  Var out As FolderItem = SpecialFolder.Desktop.Child("TableFromTextFile.pdf")
  
  If out <> Nil Then
    d.Save(out)
    out.Open
  End If
End If

Conclusion

As you see, and if this tutorial is compared with PDFTable from a RowSet, creating a PDFTable doesn’t differ too much when using a data source other than a RowSet. All you need, basically, is to keep track of the current row, know if you need to render more rows and a base data structure that can be used to retrieve the data to be rendered in a given Row/Column.

As always, you can learn more about other features provided by PDFDocument in the Xojo Documentation.

Happy Coding!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

• The control should show previews of images and PDF documents.
• The documents to be displayed can be dragged and dropped onto the control, or opened from the standard file selection dialog.
• In the case of images, they can also be added to the control using Copy and Paste.
• In any of the above cases, the path of the file in question must be received so that future actions can be carried out.

As an additional point, since we are using Xojo, the control will be cross-platform and functional on macOS, Windows and Linux.

Download the Example Project.

Preparation

Taking into account these requirements, as well as considering that the same problem may have more than one solution, this tutorial will show you how to create a control using the Composition technique. Using this technique, several graphical interface controls will be used internally and their use will be transparent to users who use it globally, either when creating their own applications or when using the control on any desktop platform.

When it comes to creating a control using the Composition technique, the DesktopContainerControl is the best candidate. A new ContainerControl-based class would internally use the following core controls:

1. The DesktopImageWell control which is ideal for displaying images.
2. The DesktopHTMLViewer control which is ideal for displaying the preview of PDF documents.

Now, while DesktopImageWell supports displaying images directly using Drag and Drop, this is not the case with the DesktopHTMLViewer control; so if the user of the control tried to drag and drop a PDF document or image when the HTMLViewer is displaying the control, it wouldn’t work.

To solve this situation it is common to add a third control. We’ll use a DesktopCanvas that will be, at all times, the top layer regardless of which underlying control (either the ImageWell or the HTMLViewer) is displayed. Thus, the DesktopCanvas would capture the event corresponding to the user dragging a file onto the global control (the class based on ContainerControl). Since it is transparent, it will not prevent the preview of the image or PDF file to be seen in the bottom layer control, at least on macOS.

But the Canvas is not transparent on Windows, in this case we need to use conditional compilation at various points in the class to modify the user interface of the main ContainerControl so that it adds a special area located under the controls preview (ImageViewer or HTMLViewer), and which will be used by the user of the control to drag and drop the corresponding files. For this we will use an additional DesktopCanvas.

Of course, we will also have to add a button to our control that will be responsible for opening the standard file selection dialog box so that the user can choose the file to preview.

To deal with another small difference between macOS and Windows, we will add a DesktopRectangle to be used as the base layer of the control (Z axis), so that it displays the typical Focus ring when the control is active and selected.

Designing the Control

With all that in mind, start a new Desktop project in Xojo. Drag a DesktopContainer from the Library onto the Navigator. It will look like this:

With the new Desktop Container1 instance selected in the Navigator, use the Inspector Panel to change the following values:

• Name: ImagePDFContainer
• Size > Width: 220
• Size > Height: 200

Next, add the Drag and Drop area which, remember, will be shown only when the control is executed on Windows. To do this, drag a DesktopCanvas from the Library and drop it in the area of the Layout Editor corresponding to the Design Editor, placing it right under the container for our own convenience.

With Canvas1 selected, use the Inspector Panel to change the following values:

• Name: DropArea
• Position > Left: 1
• Position > Top: 221
• Position > Width: 216
• Position > Height: 100

The design should look like this:

Now, add the background layer. This is the layer that will be in charge of displaying the focus ring for the control in Windows. To do this, drag a DesktopRectangle from the Library and drop it on the ContainerControl in the Layout Editor. The ContainerControl should show a red box indicating that the dragged control will be contained as a child control in the Container itself. Next, with DesktopRectangle1 still selected in the Layout Editor, use the Inspector Panel to modify the following values:

• Name: BacktroundRect
• Position > Left: 0
• Position > Top: 0
• Position > Width: 220
• Position > Height: 200
• Locking: Lock all four padlocks.

Next, add the button responsible for displaying the standard dialog box for selecting the file to preview. Drag a DesktopPushButton from the Library and drop it onto the bottom of the Container in the Layout Editor. The Container should display a red box to indicate that the button will be added as a child control in the Container itself.

Then, with Button1 still selected in the Layout Editor, use the associated Inspector Panel to change the following values:

• Name: OpenFileButton
• Position > Left: 0
• Position > Top: 0
• Position > Width: 178
• Position > Height: 22
• Locking: Closes the left, right and bottom locks. Open the lock on the top edge.
• Mac Button Style: Recessed
• Caption: Open File…

At this point, the control layout should look something like this:

Now, add the instance of the DesktopImageViewer control responsible for previewing the images. As in previous steps, drag the DesktopImageViewer control from the Library and drop it on the Layout Editor, in the upper right part of the Container; then, with ImageViewer1 still selected, use the associated Inspector Panel to change the following values:

• Name: ImagePreviewer
• Position > Left: 238
• Position > Top: -219
• Position > Width: 218
• Position > Height: 198
• Locking: Lock all four padlocks.

Drag a DesktopHTMLViewer from the Library onto the free area of the Layout Editor, just below the ImageViewer added in the previous step; Then, with HTMLViewer1 still selected in the Layout Editor, use the associated Inspector Panel to modify the following values:

• Name: HTMLPDF
• Position > Left: 238
• Position > Top: 0
• Position > Width: 218
• Position > Height: 198
• Locking: Lock all four padlocks.

At this point, the control layout should look something like this:

Finally, add the overlay to be used only when the control is executed on macOS and that is responsible for capturing the action of “Drag and Drop” files by the user. Drag a new DesktopCanvas over the Container in the Layout Editor. The Container should display a red box to indicate that the new control is being added as a child of the Container itself. With Canvas1 still selected in the Layout Editor, use the associated Inspector Panel to modify the following values:

• Name: CanvasOverlay
• Position > Left: 1
• Position > Top: 1
• Position > Width: 218
• Position > Height: 179
• Locking: Lock all four padlocks.

To make sure that all the “layers” (order of the controls on the Z axis) are as we expect, click on the “Show Tab Order” button in the Layout Editor toolbar. If they do not match the order shown in the image below, drag and drop each element to the correct position in the list:

Add Functionality

With the design of the control now complete, it is time to add its functionality. To do this, select ImagePDFContainer in the Navigator and add the following properties along with the values indicated in the Inspector Panel:

The first will be in charge of containing the message to be displayed in the “Drag and Drop” area:

• Name: DropFileMessage
• Type: String
• Scope: Public

The second will be the property in charge of storing the reference to the file (FolderItem instance) whose image/PDF is being previewed:

• Name: FileDropped
• Type: FolderItem
• Scope: Private

The last property will be responsible for containing the color to be used as the focus ring:

• Name: FocusColor
• Type: Color
• Scope: Public

Next, add the events that the control needs to consume for its operation. With ImagePDFContainer still selected in the Navigator, add the following Event Handlers along with the associated code:

Opening:

HTMLPDF.Visible = False
ImagePreviewer.Visible = False

#If TargetWindows Then
  DropArea.Top = Me.Height - 50
  DropArea.Height = 50
  DropArea.Width = BackgroundRect.Width
  DropArea.Left = BackgroundRect.Left
  BackgroundRect.Height = BackgroundRect.Height - 50
  
  HTMLPDF.Height = BackgroundRect.Height - 2
  ImagePreviewer.Height = BackgroundRect.Height - 2
#EndIf

RaiseEvent Opening

MouseDown:

Me.SetFocus
Return True

FocusReceived:

#If TargetWindows Then
  FocusColor = Color.Blue
  BackgroundRect.BorderColor = FocusColor
  DropArea.Refresh
#EndIf

FocusLost:

#If TargetWindows Then
  FocusColor = Color.Black
  BackgroundRect.BorderColor = FocusColor
  DropArea.Refresh
#EndIf

Since the Opening event is used by our ImagePDFContainer subclass, add an event definition with the same name so that instances created from it can also add their own Opening event handler and include any additional code to execute as desired.

Then, add an additional event definition (FileDropped) that will be the one sent by the ImagePDFContainer subclass to the instances created from it, and that implement it, to pass them as a parameter the FolderItem corresponding to the file opened / dragged and dropped / or , in the case of images, that have been pasted on the control.

• Name: FileDropped
• Parameters: file As FolderItem

Since we want to support pasting images onto the control, we also need to add a MenuHandler to the ImagePDFContainer subclass. To do this, with ImagePDFContainer still selected in the Navigator, select the option Add to “ImagePDFContainer” > Menu Handler…

Use the following values in the associated Inspector Panel:

• MenuItem Name: EditPaste

And add the following code in the Code Editor associated with the Menu Handler:

Var pb As New Clipboard
If pb.PictureAvailable Then
  Var f As FolderItem = SpecialFolder.Temporary.Child("temp-pict.png")
  If f.Exists Then f.Remove
  If f <> Nil Then
    pb.Picture.Save(f, Picture.Formats.PNG)
    FileDropped = f
    PreviewFile(FileDropped)
  End If
  Return True
End If

Return False

To complete this section, add a new method to ImagePDFContainer and use the following values in the associated Inspector Panel:

• Method Name: PreviewFile
• Parameters: f As FolderItem

Add the following code in the associated Code Editor:

FileDropped = f

If f <> Nil Then
  
  If FileDropped.Name.EndsWith(".pdf") Then
    ImagePreviewer.Visible = False
    HTMLPDF.Visible = True
    
    HTMLPDF.Top = BackgroundRect.Top + 1
    HTMLPDF.Left = BackgroundRect.Left + 1
    
    #If TargetWindows Then
      HTMLPDF.Height = BackgroundRect.Height - OpenFileButton.Height
    #Else
      HTMLPDF.Height = Self.Height - OpenFileButton.Height
    #EndIf
    
    HTMLPDF.LoadPage(FileDropped)
    
  Else
    
    Var p As Picture = Picture.Open(FileDropped)
    
    If p <> Nil Then
      ImagePreviewer.Top = BackgroundRect.Top + 1
      ImagePreviewer.Left = BackgroundRect.Left + 1
      
      #If TargetWindows Then
        ImagePreviewer.Height = BackgroundRect.Height - OpenFileButton.Height
      #Else
        ImagePreviewer.Height = Self.Height - OpenFileButton.Height
      #EndIf
      
      ImagePreviewer.Image = p
      HTMLPDF.Visible = False
      ImagePreviewer.Visible = True
      
    End If
    
  End If
  
  RaiseEvent FileDropped(FileDropped)
  
Else
  HTMLPDF.Visible = False
  ImagePreviewer.Visible = False
End If

Add Functionality to Controls

Now it’s time to add functionality to the controls. Select the CanvasOverlay item in the Navigator and add the following Event Handlers along with the code given below:

Opening:

Me.AcceptFileDrop("application/pdf")
Me.AcceptFileDrop("image/png")
Me.AcceptFileDrop("image/jpg")

#If TargetWindows Then
  Me.Visible = False
#EndIf

DropObject:

#Pragma Unused action

If obj.FolderItemAvailable Then
  PreviewFile(obj.FolderItem)
End If

MouseDown:

#Pragma Unused x
#Pragma Unused y

Self.SetFocus

Now select the DropArea item in the Navigator and add the following Event Handlers along with the code indicated below:

Opening:

Me.AcceptFileDrop("application/pdf")
Me.AcceptFileDrop("image/png")
Me.AcceptFileDrop("image/jpg")

#If TargetMacOS Then
  Me.Visible = False
#EndIf

DropObject:

#Pragma Unused action

If obj.FolderItemAvailable Then
  PreviewFile(obj.FolderItem)
End If

Paint:

#Pragma Unused areas

g.DrawingColor = FocusColor
g.PenSize = 2.0
g.DrawRectangle(0, 0, g.Width, g.Height)
g.PenSize = 1.0

If DropFileMessage <> "" Then
  
  g.DrawingColor = Color.Black
  
  Var textLength As Double = g.TextWidth(DropFileMessage)
  Var x, y As Double
  
  x = Me.Width / 2 - textLength / 2
  y = Me.Height / 2 + g.TextHeight / 2
  
  g.DrawText(DropFileMessage, x, y)
  
End If

Now select the HTMLPDF item in the Navigator and add the Event Handlers along with the code indicated below:

MouseDown:

#Pragma Unused x
#Pragma Unused y

Self.SetFocus

Next, select the ImagePreviewer item in the Navigator and add the following Event Handlers along with the code below:

MouseDown:

#Pragma Unused x
#Pragma Unused y

Self.SetFocus

Finally, select the OpenFileButton item in the Navigator and add the following Event Handlers along with the code indicated below:

Pressed:

Var f As FolderItem = FolderItem.ShowOpenFileDialog("")

If f <> Nil Then
  Self.PreviewFile(f)
End If

Testing the ImagePDFContainer Control

We have completed the design and added the required functionality to our control, now it is time to add an instance to the project window so we can test its operation.

Select Window1 in the Navigator so that the associated Layout Editor is displayed. Next drag ImagePDFContainer from the Navigator and drop it onto the Layout Editor, using the following values in the associated Inspector Panel:

• Size > Width: 220
• Size > Height: 200
• Locking: Lock all four padlocks
• Appearance > Allow Focus Ring: Enabled
• Behavior > Allow Focus: Enabled.
• Behavior > Allow Tabs: Enabled.

With ImagePDFContainer1 selected in the Navigator, add the following Event Handlers along with the code below:

Opening:

Me.DropFileMessage = "Drop Files Here"

FileDropped:

LastFolderItemNameLabel.Text = file.NativePath

As you can see, this is referring to the LastFolderItemNameLabel control that we have not yet added to the window layout yet; So, let’s do that.

Select Window1 in the Navigator to access the associated Layout Editor. Drag a Label control from the Library and drop it onto the bottom of the window in the Layout Editor, then use the following values in the associated Inspector Panel:

• Name: Label1
• Position > Left: 28
• Position > Top: 360
• Position > Width: 150
• Position > Height: 20
• Locking: Lock the left and bottom padlock. Unlock the top and right locks.
• Text: Last FolderItem Path:

Add a second Label from the Library to the right of the previous one, using the following values in the associated Inspector Panel:

• Name: LastFolderItemNameLabel
• Position > Left: 190
• Position > Top: 360
• Position > Width: 390
• Position > Height: 20
• Locking: Locks the left, bottom and right padlocks. Unlock the top lock.
• Text: (empty)

Run the Application

Ready! Run the application and try dragging and dropping image files (JPEG or PNG), as well as PDF files on the control. You should see the change on the fly, showing the most appropriate viewer for each type of file. It will also display the path of the file at the bottom of the window.

You can also click on the button to select the file to display or try copying images and pasting them directly on the control. If you do this, a temporary file will be created so that one of the initial requirements is satisfied: being able to continue working with the file corresponding to the image or PDF document.

As I mentioned at the beginning, this is just one of the possible implementations. I hope you have learned a few things along the way in, for example:

• Redefine Events consumed by a base class.
• Create your own Class Events and how to launch them to “pass” information to the instances created from said class.
• Capture and work with Menu Handlers.
• Use of Conditional Compilation so that certain sections of code run only on one platform or another.
• And, of course, how to make several UI controls cooperate and present themselves as a single control to the developer and end user who are going to use them.

I hope you found it interesting. You are welcome to modify and expand the project to better suit your purposes!

Have fun and keep coding with Xojo!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

The use of this control is pretty straightforward. Add it to the layout of a Screen in your iOS project. You can use the Inspector Panel to set the background color (by default it is white) and whether it displays the page thumbnails. Of course, the available properties can also be set via code.

Here’s how it looks running in the Simulator:

You will then need to tell the PDFViewer which PDF file to display. Do this by assigning the FolderItem to the document property of the PDFViewer control instance. The following lines of code assigns document that has been added to the Resources folder using a Copy File step in the IDE:

Var f As FolderItem = SpecialFolder.Resource("SampleDocument.pdf")

If f <> Nil And f.Exists Then
  PDFViewer1.Document = f
End If

It is also possible to change the layout of the pages in the PDFViewer with the DisplayMode property that accepts any of the values of the MobilePDFViewer.DisplayModes Enumeration:

• SinglePage
• SinglePageContinuous
• TwoUp
• TwoUpContinuous

It is possible to get the number of pages in the document through the Pages property. You can jump to a specific page in the PDF by setting its number using the Page property.

Lastly, another useful feature of the PDFViewer control is being able to call the Content method in order to retrieve all the text found in the document. To learn more about all the great new PDF features in Xojo, check out the PDF tag of the Xojo Programming Blog.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Just as with Xojo’s WebChart, DesktopChart and MobileChart offer the following chart types: Line, Bar, Pie, Doughnut, PolarArea, Scatter, Bubble and Radar. You can access these charts using the Inspector Panel or via code through the Mode property. You can even change the Mode (or chart type) at runtime on Desktop and Mobile.

Line and Bar types are similar; both display sets of data that have been set to Line or Bar Modes. Display as many data sets as you need in your DesktopChart or MobileChart by setting the Mode to Line or Bar. The only difference is how these will be displayed along the x axis.

To better understand, let’s write some code in the Opening Event Handler of a DesktopChart control added to a Desktop project:

Var labels() As String
Var firstSetOfData() As Double
Var secondSetOfData() As Double
Var thirdSetOfData() As Double

For n As Integer = 0 To 9
  labels.add "LB"+n.ToString
  firstSetOfData.add System.Random.InRange(0,1000)
  secondSetOfData.add System.Random.InRange(0,1000)
  thirdSetOfData.add System.Random.InRange(0,1000)
Next

Me.mode = DesktopChart.Modes.Line
Me.Title = "Chart Example With Two Datasets"
Me.AddLabels labels

Var DS1 As New ChartLinearDataset("DS1", Color.Blue, True, firstSetOfData)
DS1.ChartType = ChartLinearDataset.ChartTypes.Line

Var DS2 As New ChartLinearDataset("DS2", Color.Red, True, secondSetOfData)
DS2.ChartType = ChartLinearDataset.ChartTypes.Bar

Var DS3 As New ChartLinearDataset("DS2", Color.Green, True, thirdSetOfData)
DS3.ChartType = ChartLinearDataset.ChartTypes.Bar

Me.AddDatasets DS1, DS2, DS3

This is how it will look when the Chart has been set to Line, displaying three data sets: one of which has been set to Line and the other two to Bar:

As you can see, when the ChartType is Line, the data sets that are set to Line start drawing at the origin of the X axis, where the labels are also drawn for each column of data. This also happens when drawing data sets whose ChartType is set to Bar; thus, the first bar on the first column has half the width.

Below shows the same data sets but the ChartType is Bar. Now the Bar data sets overlay the position for the labels drawn along the X axis (they are centered on each column), and also have full the width. However, because of that, the data set whose ChartType is set to Line starts drawing at half the width of the column.

You can add as many new data sets as you want, remove them, update their values, color, etc. The chart will update to reflect the changes, including the minimum and maximum values displayed in the Y axis. Keep in mind, if a chart’s Mode has been set to Line or Bar it will only display data sets created as ChartLinearDataset (by default they are set to the Line ChartType). WebChart will behave the same, starting with Xojo 2023r1.

One difference to note when using ChartLinearDataset is that you can set the Transparency property ranging from 0 (fully opaque) to 100 (fully transparent), as well as the CornerSize when the ChartLinearDataset ChartType is set to Bar.

ChartDataset and Chart Modes

I already showed you that a chart set to Line or Bar only displays data sets created from the ChartLinearDataset class. A similar rule applies when the chart is set to other Modes. For example, Pie, Doughnut, PolarArea or Radar charts only display data sets created from the ChartCircularDataset class.

• In the same vein, Scatter and Bubble charts only display data sets created from the ChartScatteredDataset class.

DesktopChart and MobileChart, additional Properties

DesktopChart and MobileChart offer additional customisation properties. For example, you can set the font, font size and font color for the title, legend, labels and values on the Y axis.

When setting the maximum font size used for the drawing of the Y axis values based on the chart control instance size (height), if the height of the control is not enough to display the values at the specified font size, it automatically adjusts.

Other properties to further customize the look of the chart include BackgroundColor and GridColor.

Tip: You may want to set the color to Color.Clear if you want your charts to be drawn or “visible”, like if you plan to layout the chart control on top of other UI controls.

In addition, you can control whether or not to display that popup that shows the underlying value as the user moves the cursor (or while dragging their finger, on iOS). This is done through the AllowPopover property (True, by default).

Set the background and text color in the Popover using the PopoverBackgroundColor and PopoverTextColor properties. These expect a ColorGroup instance, so they can adjust when the control is in Light or Dark Mode.

Getting informed

As you may expect from their WebChart counterpart, DesktopChart and MobileChart offer a Pressed event handler to receive the index and dataset instance over which the user clicked/tapped.

Because the chart control can handle different ChartDatasets you’ll probably want to cast the received ChartDataset instance received in the Pressed handler to the right one before proceeding with any actions that are not common to all kind of ChartDatasets.

Draw it!

You can call the DrawInto method on a chart, provide the expected graphic context and also the left and top values to proceed with the drawing. For example, this is what a DesktopChart looks like when drawn on a Picture of the same size:

It is also possible to render the chart to PDF in a vectorial way using the AddChart method on a PDFDocument instance. The parameters this method expects are the chart instance itself, the X and Y values (where it will be placed in the current PDF page), and the width and height values for the rendering.

For example, this code will create a PDF file in the Desktop with the same height value of the chart instance, with the width set to the width of the page, minus the margins:

Var d As New PDFDocument
Var g As Graphics = d.Graphics
d.AddChart(chart1, 20, 20, g.Width-40, chart1.Height )
d.Save(SpecialFolder.Desktop.Child("ChartPDF.PDF"))

In summary

As you can see, now it is possible to add Graphical Charts to your Desktop and iOS projects with the same ease and in the same way it is already possible on web projects, plus some more customization options. Watch a quick video on this topic. No license is required to learn, develop and test your projects in the latest Xojo release! Download Xojo 2023r1 today!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

But before we dive into the code, this example project requires the “EddiesElectronics.sqlite” SQLite database file. You can find the Eddie’s Electronics example, along with the other example projects provided with Xojo, in the Examples section of the Project Chooser. Because I am such a kind person, you can also download it directly from this link.

And, if you want, it is also possible to download the resulting Xojo Project file (for Desktop) from this link.

I’m pretty sure you will be able to adapt the example project so it works for you with other databases too!

Helper class to the rescue!

All the work of drawing the table in the PDF document will be done by a helper class. That is, a class that we are going to use to “delegate” the work. With Xojo open and a new Desktop project created, the first thing we are going to do is add a new Class to the project (Insert > Class).

With the added Class selected in the Navigator, go to the associated Inspector Panel and use the following values:

• Name: PDFRenderer
• Interfaces: Click on the “Choose” button and select the PDFTableDataSource class interface

The just added Class will be populated with all the methods defined by the PDFTableDataSource class interface. Do not worry about them now.

Next, let’s add a few properties to our PDFRenderer class:

• Name: data
• Type: RowSet
• Scope: Protected

• Name: document
• Type: PDFDocument
• Scope: Protected

• Name: DrawingFromRowSet
• Type: Boolean
• Scope: Protected

• Name: Headers()
• Type: String
• Scope: Protected

We are going to use the DrawingFromRowSet as a flag, so the PDFRenderer knows when the table is going to be created from a RowSet. You could use any other data source, you are limited to RowSet. That’s just something you will need to implement yourself! Take it as an exercise.

Next, add a new Method to the PDFRenderer class (while still selected in the Navigator) using the following values in the associated Inspector Panel:

• Name: Constructor
• Parameters: document As PDFDocument
• Scope: Public

And type the following line of code in the associated Code Editor:

Self.Document = document

Yep, it is truly that simple. Assign the received PDFDocument object to the “Document” property of the object created from the PDFRenderer class.

Add a second method using the following values:

• Name: DrawTable
• Parameters: rs As RowSet, headers() As String
• Scope: Public

And type the following code in the associated Code Editor:

// This is the method we call on the Class to draw
// a table on a PDFDocument based on a RowSet

If document <> Nil And rs <> Nil Then

  // Assign the received RowSet to the "Data" property
  Self.data = rs

  // Assign the received headers to the "Headers" property
  Self.Headers = Headers

  // Hey! We are going to create a table from a RowSet
  // so we use a Boolean property as a flag for that
  // (Yeah, we can do it using other techniques, but this
  // is easy enough for this purpose… while leave this
  // helper class "open" enough for drawing tables based on other
  // data sources).
  Self.DrawingFromRowSet = True

  // How many columns are we going to draw?
  // Well… as many as columns in the RowSet.
  Var totalColumns As Integer = rs.ColumnCount

  // This is going to be the "drawable area" on the page
  // for the table = total page width less the left and right margins
  Var totalWidth As Double = document.Graphics.Width - 40 // 40 = 20 points left/right margins

  // Creating the PDFTable object here!
  Var table As New PDFTable

  // We want to repeat the headers on every page
  table.HasRepeatingHeader = True

  // Setting the column count for the table
  table.ColumnCount = totalColumns

  // …and the width for every column.
  table.ColumnWidths = CalculateColumnWidths(TotalWidth, totalColumns)

  // The object from this class will be the responsible
  // for handling all the methods associated with the
  // PDFTableDataSouce Class Interface
  table.DataSource = Self

  // Setting the Top and Bottom margins for the drawing
  // of the table on every PDF page
  table.TopMargin = 20
  table.BottomMargin = 20

  // …and finally we instruct the PDFDocument object
  // to draw the table!
  document.AddTable(table, 20, 0)

  // Lastly, clearing the flag
  Self.DrawingFromRowSet = False

End If

As you can see here, we are calling the “CalculateColumnWidths” method in order to get the expected string for the column widths for the PDFTable.ColumnWidths property; so add a new method to the PDFRenderer class using the following values:

• Name: CalculateColumnWidths
• Parameters: TotalWidth As Double, NumberOfColumns As Double
• Return Type: String
• Scope: Protected

And type the following snippet of code in the associated Code Editor:

Var ColumnWidth As Integer = TotalWidth / NumberOfColumns
Var s() As String

For n As Integer = 0 To NumberOfColumns-1
  s.Add(Str(ColumnWidth))
Next

Return String.FromArray(s, ",")

PDFTableDataSource Methods with RowSet data!

Let’s fill the required methods from the PDFTableDataSource class interface so they work in combination with the received RowSet.

AddNewRow Method

Add this snippet of code for the “AddNewRow” method:

If DrawingFromRowSet And data <> Nil Then

  // We are going to draw as many rows as rows are in the
  // "data" rowset
  Return rowCount <> data.RowCount

End If

As you can see, that fragment of code will only run when both conditions are meet. That is, when the “DrawingFromRowSet” is set to True and the “data” property is set to a not niled RowSet. If this is the case, we then instruct our PDFTable to set the number of rows to be drawn to the same number of rows in the RowSet.

Completed Method

This is the method that will be called once the drawing of the PDFTable has been completed. We will use it to draw the page numbers at the bottom of every page in the PDFDocument. As you probably already know, it is really easy to change the active graphic context to a given page of the PDF document using the CurrentPage property, so we will use that to iterate every one of our PDF document pages, adding the page number to it as a footer.

This is the snippet of code responsible for doing just that:

// This method is called once the table has been drawn
// so let's "print" the page number on every page
// of the PDF Document

Static pageNumber As String = "Page: "

If document <> Nil Then
  Var g As Graphics = document.Graphics

  For n As Integer = 1 To document.PageCount
    document.CurrentPage = n
    g.DrawText(pageNumber + Str(n), g.Width - g.TextWidth(pageNumber+Str(n))-20, g.Height-g.FontAscent)
  Next

End If

HeaderHeight Method

This is the method called so we can set the PDFTable the desired height for the drawing of the Header. In this case we are going to use a fixed value: 20 points. The code for that method is:

// Fixed header height
Return 20

PaintCell Method

This is the method responsible for drawing every cell of the PDFTable. It receives as parameters the Graphic context for a particular cell (so its origin is at 0,0) and the row and column values corresponding for such cell.

In this case, draw the outline of a rectangle for the cell plus the text itself retrieved from the RowSet based on the received Column value. The text will be draw vertically centered in the cell:

If DrawingFromRowSet And data <> Nil Then
  // Drawing the outer rectangle for the cell
  g.DrawRectangle(0, 0, g.Width, g.Height)

  // retrieving the text to be drawn from the RowSet,
  // using the column parameter for that.
  Var s As String = data.ColumnAt(column)

  // Centering vertically the text on the table cell
  // while the X offset is fixed at 5 points.
  g.DrawText(s, 5, g.Height / 2 + g.FontAscent / 2)

  // Have we drawn all the columns for this row?
  If column = data.ColumnCount - 1 Then

    // if that is the case, then move to the next row
    // in the RowSet!
    data.MoveToNextRow
  End If

End If

PaintHeaderContent Method

This is the method called in order to draw the Header of the table itself. It is a more simple version of the previous method. In this case, the text will be centered both vertically and horizontally on every header cell:

If column <= Self.Headers.LastIndex Then

  Var s As String = headers(column)
  g.DrawingColor = Color.Black
  g.FillRectangle(0, 0, g.Width, g.Height)
  g.DrawingColor = Color.White
  g.DrawText(s, g.Width / 2 - g.TextWidth(headers(column)) / 2, g.Height / 2 + g.FontAscent / 2)

End If

RowHeight Method

As it happen with the HeaderHeight method, this is the method called to set the height for a given row. As we did for the HeaderHeight method we are going to use a fixed value of 20 points, so type the following line of code in the associated Code Editor:

Return 20

Testing The PDFRenderer class

In order to test our PDFRenderer class in combination with a RowSet object, we need to do some additional work. First, select the Window1 window in the project Navigator and add a property using the following values:

• Name: db
• Type: SQLiteDatabase
• Scope: Private

Next, click the Window1 window in the Navigator so it is displayed in the Layout Editor. Then, drag a DesktopLabel from the Library and drop it on the left/top edge of the layout observing the aligning guides so it leaves the expected margin over the left and top edges of the Window. Use the dragging handlers of the DesktopLabel on the layout to resize it to the maximum width (once again, less the expected margins). Use the following values in the associated Inspector Panel:

• Locking: Left, Top and Right locked. Bottom, unlocked.
• Multiline: on.
• Text: This example project needs to use the EddiesElectronics.sqlite database file. Click on the button in order to select it!

The layout at this point should look like this:

Now, drag a DesktopButton from the Library and drop it below the previous Label so it is horizontally centered, using the following values in the associated Inspector Panel:

• Caption: Select EddiesElectronics database file

The finished layout should look like this:

Double click the button to add the “Pressed” Event Handler. Then, add the following code in the associated Code Editor:

Try

  // Assigning SQLite object to property
  db = New SQLiteDatabase

  // Setting the database file to the SQLite object
  db.DatabaseFile = FolderItem.ShowOpenFileDialog(".sqlite")

  // Just a simple check to see if this is the expected
  // file based on the name = "EddiesElectronics.sqlite"

  If db.DatabaseFile = Nil Or db.DatabaseFile.Name <> "EddiesElectronics.sqlite" Then Return

  //…and "connecting" to it!
  db.Connect

  // Let's select all the rows from the Customers table
  Var rs As RowSet = db.SelectSQL("SELECT FirstName,LastName,Address FROM Customers")

  // Creating a new PDFDocument Instance
  Var d As New PDFDocument

  // Creating the PDFTable renderer helper object (we pass the PDFDocument object to it in the Constructor)
  Var PDFRender As New PDFRenderer(d)

  // These will be the headers drawn in the Table
  Var headers() As String = Array("Name", "Surname", "Address")

  // And let's instruct the PDFTable renderer helper to draw the table
  // based in the SQLite database rowset we got in the previous step
  PDFRender.DrawTable(rs, headers)

  // …and save the resulting PDF File to the Desktop
  Var f As FolderItem = SpecialFolder.Desktop.Child("TableFromRowSet.pdf")

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

Catch e As DatabaseException
  System.DebugLog(e.Message)
Catch e As NilObjectException
  System.DebugLog(e.Message)
End Try

As you can see, all this does is create a new SQLiteDatabase object and assign it to the “db” property. Then, we set the “DataBaseFile” property of that object to the file selected by the user. The code will do a simple check to see if the selected file is the expected “EddiesElectronics” database file. If that is the case, then it will connect to the database, getting a RowSet from a simple query that retrieves the “name”, “surname” and “address” columns from the “Customers” database table.

After creating the PDFDocument instance, the code creates a new instance from our PDFRenderer class and calls the “DrawTable” method on that object passing along both the RowSet and the Headers we want to use for drawing the table.

Lastly, the PDFDocument will be saved to disk and opened in the by default PDF viewer app.

Run the app, select the “EddiesElectronics” SQLite database file and the resulting PDF file will be opened after a few seconds. It will display the table generated from a RowSet data source!

In Summary

It is quite possible to draw tables in a PDFDocument when the data to render comes from a RowSet. Nearly everything was done through the use of a helper class. As always, this can be improved in several ways! For example, we are using a fixed height for every row of the table, but in a more realistic scenario may be using variable heights for the table rows based in the height / amount of data to be drawn. That is something that is doable too!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

In order to merge cells in a table’s row, the PDFTableDataSource class interface includes a new method: MergeCellsForRow(row As Integer, ByRef CellsToMerge() As CellRange) As Boolean. This method will be called for every table row to be drawn so you can provide the range of cells to merge as a CellRange instance.

For example, the following statement will merge all the cells for a row in a five column table:

CellsToMerge.Add New CellRange(0,4)

Where CellsToMerge is an array parameter received by reference. So, if we apply the previous sentence to every even row in the table:

If row Mod 2 = 0 Then
  CellsToMerge.Add New CellRange(0,4)
  Return True
End If

We will get the following PDF as result (based on the PDF table example project):

Top and Bottom Margins

In addition, the PDFTable class now has two new properties: TopMargin As Double and BottomMargin As Double. As you can guess these will let you set the top and bottom margins for the table when it is added to the PDF document pages; specially interesting when the table is going to spread several pages because you won’t need to do any maths in order to know when a new page needs to be added to the document, PDFDocument will take care of it based on the provided values plus the height value of every row to be drawn!

Hey mate, the table has been drawn!

Lastly, we also added the Completed(x As Double, y As Double) method to the PDFTableDataSource class Interface, so your code can know the right spot at which the table has finished drawing itself. This is specially interesting when the table spreads several pages, so you can get the last X and Y coordinates of the table drawing in order you can continue adding new content to the PDF page right after it!

For example, the following code in the Completed method of our example will render the “Drawing Table Completed!” text in the last added page, just below the drawing of the table, adding 20 points to the received Y value and using the same X value so the left margin for the text is the same that the one used to draw the table:

In Summary

These additions give you more control when drawing the tables to your PDFDocuments: setting both the upper and lower margins for the page, getting informed when the table has finished drawing itself, and the ability to merge cells independently on every row of the table!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

You can download the example project from this link.

Features of Tables in PDFDocument

The main features available with tables in PDFDocument are:

• PDFTable / PDFTableDataSource is compatible with Desktop, Web, Console and RaspberryPi projects
• Variable height rows
• Automatically add new pages to the PDF
• The ability to repeat (or not) the table header at the start of every new page added

In order to achieve this, the PDFTable class works side by side with the PDFTableDataSource class interface. This class interface declares the methods that will be called by a given PDFTable instance in order to generate the table on the fly.

• PDFTableDataSource

Because it is a class interface, you will be able to add it to any window/web page or any class/subclass you create, so it can work as the provider of the data in the drawing of a given PDF table.

The PDFTableDataSource has these five methods:

• AddNewRow(rowCount As Integer) As Boolean– The rowCount parameter contains the value of the rows already added to the table. Returning True from this method will add a new row to the table; otherwise it will end the creation of the associated table.
• HeaderHeight As Double– In the implementation of this method you will set the height value used in order to draw the table header.
• PaintCell(g As Graphics, row As Integer, column As Integer)– This is the method called by the PDFTable instance in order to draw the cell for the row/column pair stored in the associated parameters. The method receives its own graphic context in the ‘g’ variable, so you can use any of the supported methods and properties of the Graphic class to draw the contents in the table cell.
• PaintHeaderContent(g As Graphics, column As Integer)– This is the method called by the PDFTable instance every time it needs to draw the header of the table. As you can see, it receives as parameters the column number and its own graphic context.
• RowHeight As Double– This is the method called by the PDFTable instance so your code can set the height for the current row.

PDFTable

This is a really simple class exposing a total of four properties:

• ColumnCount As Integer– This is the property that sets the number of columns for the table to be drawn.
• ColumnWidths As String– This is the property that sets as a string the width of every column in the table, separated by the comma character.
• DataSource As PDFTableDataSource– This is the property that sets the object acting as the data source object for the table. Remember that such an object needs to implement the methods declared in the PDFTableDataSource class interface.
• HasRepeatingHeader As Boolean– Use this property to instruct the PDFTable instance if it needs to repeat the header on every new page that is added to the document as the table is generated.

For example, the following fragment of code will create a table with a total of three columns that have the same size. The table will be drawn horizontally centered in the page. The object acting as the data source for the table will be the same where this snippet of code has been added, that is: ‘Self’:

Var d As New PDFDocument

Var tTable As New PDFTable
tTable.ColumnCount = 3
tTable.ColumnWidths = "150,150,150"
tTable.DataSource = Self
tTable.HasRepeatingHeader = True

The way to add a PDFTable instance to the current page of the PDF document is through the AddTable(table As PDFTable, x As Double, y As Double) method; for example:

Var x As Double = d.PageWidth/2 - 450/2

d.addTable(tTable,x,20)

PDFTable in Practice

In this example, you can see how to create a PDF document with a table added to it (horizontally centered on the pages). This table will have three columns equally sized and a total of 100 rows with a variable —random— height—, and giving the option to the user so they can choose to repeat the table header on every new page added to the document or not.

The cell contents of the table will be chosen randomly, varying between filling the cell with a random color, drawing text with the row and column numbers for the cell, rendering an image that has been added to the project, or keeping the cell empty.

Create a new Desktop project. With the Window1 selected in the Navigator, click on the “Choose…” button found in the associated Inspector Panel under the Interface section. This action will open a new window displaying all the available Class Interfaces. Select the PDFTableDataSource entry and confirm the selection click the Ok button.

As result, the methods declared by the PDFTableDataSource are now added to the Window1 item.

Grab a CheckBox control from the Library and drop it in the upper-left corner of the window in the Layout Editor. Use the associated Inspector Panel to change the following values:

• Name: RepeatHeaderCB
• Visual State: Checked

In order to complete this basic user interface, drag a Button control from the Library and drop it in the upper-right corner of the window in the Layout Editor. With Button1 selected in the Navigator, choose the Add to “Button1” > Event Handler… option from the contextual menu. Next, select the Pressed event from the resulting window and confirm the selection so it is added to the Window1 object.

With the Pressed event selected in the Navigator, add the following fragment of code in the associated Code Editor:

Var d As New PDFDocument

Var tTable As New PDFTable
tTable.ColumnCount = 3
tTable.ColumnWidths = "150,150,150"
tTable.DataSource = Self
tTable.HasRepeatingHeader = RepeatHeaderCB.Value

Var x As Double = d.PageWidth/2 - 450/2

d.addTable(tTable,x,20)

d.Save(SpecialFolder.Desktop.Child("Table.pdf"))

Drop any image you want to use from your computer drive into the Xojo’s IDE Navigator. Our example uses an image named “XojoLogo100”. When adding your own image, you can opt to rename it to the name name used in the code of this example, or changing all the references where “XojoLogo100” is referenced to the name of your image.

Now it is time to implement the code in every one of the five methods required by the PDFTableDataSource class interface.

In the AddNewRow method:

Return rowCount < 100 // Our example table has a total of 100 rows.

In the HeaderHeight method:

Return 30 // This is the height for the cells of the header in the table.

In the PaintCell method:

Var rd As New Random

Var option As Integer = rd.InRange(1,4)

Select Case option

Case 1

  Var s As String = "row: " + row.ToString + " column: " + Column.ToString
  Var h As Double = g.Height/2 + g.TextHeight/2
  g.DrawText s,5,h

Case 2

  g.DrawPicture(XojoLogo100,0,0)

Case 3

  g.DrawingColor = Color.RGB(rd.InRange(0,255), rd.InRange(0,255), rd.InRange(0,55))
  g.FillRectangle(2,2,g.Width-4,g.Height-4)

Case 4

 // Empty cell
End Select

g.DrawingColor = Color.Black
g.DrawRectangle 0,0, g.Width,g.Height

And this is the code we will use in order to draw the content of the table Header cells in the PaintHeaderContent:

Var tRandom As New Random

Var c As Color

Select Case Column
Case 0
  c = color.Red
Case 1
  c = Color.Green
Case 2
  c = Color.Blue
End Select

g.DrawingColor = c
g.FillRectangle 0,0,g.Width,g.Height

Var s As String = "Column: " + Column.ToString

Var x, y As Double
x = (g.Width/2) - (g.TextWidth(s)/2)
y = (g.Height/2) + (g.TextHeight/2)

g.DrawingColor = color.Black
g.DrawText s,x, y

Now add the code responsible for setting the height of every new row added to the table in the RowHeight method. As you can see, this value is a random value between 25 and 100 points:

Var rd As New Random

return rd.InRange(25,100)

Running the App

Run the app, click on the button and you will see how a new PDF document named “Table.pdf” is created in your computer desktop. The number of pages of the PDF document may vary because the height of the table rows vary on every iteration.

This time, unselect the checkbox and click the button to create the PDF document again. Now, the table header is only rendered in the first page of the document.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

More Control with PDFForm Controls

It is possible to add forms to your PDF documents using controls as text fields, text areas, list boxes, radio buttons, check boxes, popup menus, combo boxes, etc. Starting with Xojo 2022r3 you’ll be able to set if the items of PDFComboBox, PDFListBox and PDFPopupMenu are displayed sorted or as they were added using the Boolean IsSorted property.

As for the PDFTextArea and PDFTextField controls, there is a new property AllowSpellChecking so you can set if these will enable spell check or not. And in the case of the PDFTextField, it is also possible to set the HasPassword property so the text typed by the user is substituted in the PDF document with the usual replacement character, hiding what the user is typing from prying eyes!

Dealing with TOC Indexes

Lastly, there are also improvements to dealing with TOC creation in your PDF documents. For example, you can get now the Parent instance from a PDFToc entry through the Parent property; and there are new methods to get all the child items hanging from a PDFTOCEntry —Entries() As PDFTOCEntry()— and to remove existing entries from a PDFTOCEntry instance: PDFTOCEntry.RemoveEntry(ParamArray entries As PDFTOCEntry) and PDFTOCEntry.RemoveEntry(entries() as PDFTOCEntry).

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Encrypting PDF files with PDFDocument is based in the use of the PDFPermissions class. You’ll need to create a new instance of the class passing along the “Owner” and “User” passwords. For example:

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

Var p As New PDFPermissions("OwnerPassword","UserPassword")

In addition, you can set other properties for the PDFPermissions instance; all of them are read/write and will be applied by the PDF viewer app for when the document is opened using the “user” password.

• AllowCopyingContents is set to False by default. When set to True it will allow copying contents from the PDF, as for example the selected text or image.
• AllowModifyingContents is set to False by default. When set to True it will all to modify the contents of the protected PDF document.
• AllowPrinting is se to False by default. When it is set to True it will be possible to print the PDF.

Once the PDFPermissions instance has been created and the desired properties had been set, all you need to do is to assign such instance to the Permissions property for the PDFDocument instance you want to encrypt:

d.Permissions = p

Then, when it’s saving the document to a file, PDFDocument will encrypt all the streams of data containing sensitive information, as it can be the text or Images rendered on every one of the PDF pages plus the metadata information itself. The used encryption algorithm is AES 128 bits.

That’s all! You can distinguish an encrypted PDF file from an unencrypted one because, usually, the first one will be displayed with the image of a Lock in the icon. When you open an encrypted PDF in the viewer app you’ll be asked to type a password. If you enter the passord set to the “Owner” user, you’ll be able to do all the kind of operations allowed by the viewer app, while if you enter the “User” password, then the kind of options available will be determined by those set using the PDFPermissions properties.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Currently, Xojo’s PDFDocument supports the most common type of annotations for PDF – you know those little yellow boxes displayed like sticky notes on the pages of the PDF document that display their contents when clicked on.

Now with Xojo 2022r2 and later you have more options! And while most of these don’t look like “real” annotations or like something made using the Graphics methods, they will behave as the annotations you are familiar with using in PDF. What I mean by this is that they will display the associated text for the annotation while also allowing the user to Accept/Decline the annotation or interact with them by adding, for example, new replies.

Before reviewing the new options, let me just remind you: The PDF Standard dictates how some features must be implemented for a PDF. After that, it is up to the developers of the PDF viewer app to decide what features are implemented, keep in mind results can vary depending on the PDF viewer you or your user chose to use. As other many things related with PDF files, don’t expect every PDF viewer apps out there to support or adhere to the annotations outside of the most basic ones.

Adobe is the original creator of the PDF specification and its free PDF viewer, Acrobat Reader app does support everything Xojo’s PDFDocument offers.

Attaching Files to the PDF

You’ll be able to embed any kind of file (except for those based in a Bundle structure) into the PDF document itself, for example an Excel file, a Hi-Res image, etc. Then the user viewing the PDF document will be able to open the attached file clicking in the annotation using whichever PDF Viewer app their computer/device has installed for the attached file format. Because this is an annotation, the user will be able to also edit the annotation or add new replies to it.

This is an example about how to create these kind of annotations:

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

Here exampleFile is a FolderItem property that has been added to the project and that’s pointing to the file to embed.

And this is how it looks like in the resulting PDF file:

Callout Annotations

These kind of annotations are perfect for pointing our or calling attention to any other item in the PDF page. They are highly customizable- you can decide for example a solid or dashed line, the termination of the line, the color and, of course the text to be displayed in the annotation itself.

This is an example showing how to add a Callout annotation to a 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.Text = "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

Where kSampleText is a Constant added to the project containing some sample text to be put in the page of the PDF.

And this is how the Callout will look like when opening the resulting PDF file in the viewer app:

Line Annotations

A “Line” annotation displays a straight line on the page with a text caption inside the line or above it.

It is also possible to add leader lines to both sides of the main line (with possitive or negative values) plus set other properties as the type of the line (solid, dashed, etc), the kind of termination used on both ends of the main line (i.e: open/close arrow, butt, circle, diamond, square…), the drawing color, line width or font size.

This is how a Line annotation looks like when the resulting PDFDocument is viewed using Acrobat Reader (in this case, using Leader lines):

Video Annotations

Yes, you can embed .mp4 files in the PDF created with PDFDocument, and these will be played from the PDF itself. This will increase the size of the generated PDF file because it will add the size of the embedded mp4 file itself! So it is good practice to optimize the video files as much as possible and use the video resolution you want them to be played and not a higher one.

You can also add this kind of content as an Attached File annotation too. In both cases the data of the file will be embedded in the generated PDF file. The main difference in this case is that the mp4 file will be opened using an external app and that you’ll be able to include other video file format besides .mp4.

The way to add this kind of annotation to a PDFDocument instance is quite simple, for example:

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

Where exampleVideo is a FolderItem Property that has been added to the project. This is how a video annotation will look like when opening the resulting PDF in Acrobat Reader:

Sound Annotations

In addition to video annotations, it is also possible to add sound files that can be played from the PDF itself. In this case, the audio files need to be in AIFF format with 2 audio channels (stereo), 16 bits of resolution and a sampling frequency of 44,1 kHz.

As it is the case with video annotations, you can opt to add this kind of content as an Attached File annotation, so it will be opened with an external app and opens the range of sound file formats you can embed into the PDF.

The way to add Sound annotations using PDFDocument is shown here:

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

Here exampleSound is a FolderItem Property added to the project. And this is how a Sound annotation will look when the PDF document is opened using Acrobat Reader:

Markup Annotations

A Markup annotation is intended to mark an underlying text content using any of the different available types, for example “Highlight”, “Squiggly” (usually used to mark a text that needs some kind of correction), “Underline” or “Strikeout”. Besides the Markup type, it is also possible to set the color of the annotation.

For example, the following snippet of code adds two Markup annotations to the page of the PDFDocument using the Highlight and Squiggly types:

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

And this is how it looks when the resulting document is opened in Adobe Acrobat Reader:

Bonus

Let me end with one other minor improvement to PDFDocument annotations: starting with Xojo 2022r2 all of them include metadata information about the creation and modification date and time. this information will be displayed as part of the annotation metadata when the item is selected in the viewer app.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

The solution is to use the PageCount and CurrentPage properties in Xojo’s PDFDocument class. The PageCount property gives the total number of pages in the PDF, and the the CurrentPage property (read/write) can be used to reach a given page within a PDF being created. This way, when we assign a new value to the CurrentPage property, it will retrieve the current Graphics context for that page in order to continue adding new content.

Let’s see how this works through this example. Let’s create a 10 page PDF and then add the numbered footer on every page of the document:

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

// Adding a total of 10 pages to the PDF
For n As Integer = 1 To 9
  g.DrawText("Some sample text in page #" + n.ToString, 20, 20)
  g.NextPage
Next n

// Once we create the pages with some content on them,
// we iterate on every page in order to add the footer.
// Remember that the first page in a PDF document starts at 1!
Var x As Integer = d.PageCount
For i As Integer = 1 To x

// Here is where we set which will be the current "active" page;
// that is, the one retrieving the current Graphics context.
d.CurrentPage = i
g.DrawText("Page " + i.ToString + " of " + x.ToString, 20, g.Height - 30)
Next i

// Lastly, we save our PDF to a FolderItem.
d.Save(SpecialFolder.Desktop.Child("CurrentPage.PDF"))

Run this sample snippet of code and you’ll get a PDF on your computer Desktop. Open it using your preferred PDF viewer app and you’ll see how the second loop was able to draw again on every one of the pages from the PDF we created.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

To start, create a Web project, select WebPage1 in the Navigator and drop a WebButton from the Library onto the upper-center of the page in the Layout Editor. In the associated Inspector Panel for the button change the following property:

• Caption: Create PDF

Next, add the Pressed Event Handler to it and type the following snippet of code in the associated Code Editor:

// Nothing really interesting here
// Create a new PDFDocument instance
// and assign its Graphic context to
// a variable
Var d As New PDFDocument
Var g As Graphics = d.Graphics

// The content of the PDF
// not that much, but it works for the
// main topic we are interested in
g.DrawText("Really simple PDF content", 20, 20)

// Here is where the **important** thing starts
// Creating a new WebFile instance and assigning it
// to the wf property added to the WebPage1 page
wf = New WebFile

// This is the thing: the PDFDocument.ToData method
// returns as a MemoryBlock (Direct conversion to String)
// the inner contents of the PDF document at this point
// so assign that to the "data" property of the
// WebFile instance
wf.Data = d.ToData

// It's important to set the right MIMEType for the file
// in this case, it's a PDF file
wf.MIMEType = "application/pdf"

// We assign the file name…
wf.Filename = "SamplePDF.pdf"

// …and set the ForceDownload to true…
wf.ForceDownload = True

// …so the file is, in effect, downloaded when calling
// the Download method on our WebFile instance
Call wf.Download

// Because we want to display the PDF file in an HTMLViewer
// set the ForceDownload property back to False
wf.ForceDownload = False

// And, finally, preview the PDF Document loading it in the
// HTMLviewer added to the WebPage1 page
HTMLViewer1.LoadURL(wf.URL)

As you can see here, this simple fragment of code is in charge of creating a sample PDF document, downloading it and also previewing it in an HTMLViewer instance. Now, add an HTMLViewer control to the WebPage1 page.

Select the WebPage1 item in the Navigator again so it is visible in the Layout Editor. Next, drag the HTMLViewer control from the Library and drop it below the WebButton added in the previous step.

With the HTMLViewer1 control selected in the Layout Editor, click on the four lock icons under the Locking section from the associated Inspector Panel so they are closed.

Finally, add the expected WebFile property to the WebPage1 page using the following values in the associated Inspector Panel:

• Name: wf
• Data Type: WebFile
• Scope: Private

You’ll probably want to move this property to the Session object in your Web projects so every connected user to the app can handle their own generated PDF documents.

And… that’s all! Run the project, click the button and see how it works.

Have fun!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Why, you ask? What are the advantages of using a PDF for your presentations? PDF is portable, meaning you can distribute these files easily, usually, with a small file footprint. The content is vectorial (except for images), what means that it will look great no matter the screen resolution of the display/projector used for playing the presentation.

There is one current issue to watch out for, currently there’s a bug on macOS where Acrobat Reader is not able to apply the assigned transitions on Big Sur and later; they still work under Catalina and previous versions of macOS.

In this example project I will create a shortened version of the slides I used in the Using Xojo’s PDFDocument presentation. You’ll need to change the font names (and any other item) to those you are using and that are installed in your computer.

Setting the Viewer Options

Start by creating a new project for the target you’re most comfortable with – Xojo’s PDFDocument is cross-platform and supported on Desktop, Web, iOS and Console projects. Next, add the Opening Event Handler to the default DesktopWindow/WebWindow/MobileScreen, or choose the Run Event Handler if you chose to create a new Console Project.

Write the following lines of code in the associated Code Editor:

// Let's create a new PDFDocument instance with
// the page size set to HD resolution

Var Presentation As New PDFDocument(1920, 1080)

// Let's make sure that the fonts used are embedded in the
// document, so there are no unexpected problems when the
// PDF is opened in a device that doesn't have that
// same fonts installed

Presentation.EmbeddedFonts = True

The next lines of code will set the default for the View mode of the document when it is opened in Acrobat Reader or any other PDF reader. Since it’s a presentation, you’ll likely want the document to be opened in Full Screen mode by default, so let’s make that happen:

// Let's create a new Instance from the PDFViewerOptions class

Var ViewerOptions As New PDFViewerOptions

// And set the FullScreen property to True
// so the document will set that view size
// when opened in the PDF Viewer app

ViewerOptions.FullScreen = True

Drawing the Background of the Page

Use a linear gradient brush to fill in the background of all the slides. For convenience, create a new method for it using the following values in the Inspector Panel:

• Name: DrawPageBackground
• Parameters: g As Graphics

Type the following code in the associated Code Editor for the method:

Static backgroundfilling As LinearGradientBrush

If backgroundfilling = Nil Then
  backgroundfilling = New LinearGradientBrush
  backgroundfilling.StartPoint = New Point(g.Width / 2, 0)
  backgroundfilling.EndPoint = New Point(g.Width / 2, g.Height)
  backgroundfilling.GradientStops.Add(New Pair(0.0, &c000000))
  backgroundfilling.GradientStops.Add(New Pair(0.7, &c000000))
  backgroundfilling.GradientStops.Add(New Pair(1.0, &ccccccc))
End If

g.Brush = backgroundfilling
g.FillRectangle(0, 0, g.Width, g.Height)

All this code does is create a LinearGradientBrush instance ranging from full black to some degree of gray at the bottom of the page. Because we are not going to change the values of the gradient every time we need to call the method, it makes sense to assign it to a Static instead of a Variable.

Then the LinearGradientBrush is assigned to the Brush property of the received Graphic context and, finally, used as the “filling color” when drawing the filled rectangle.

Drawing the Header

Now add the method that will be responsible for drawing the header shared by all the slides. Use the following values in the Inspector Panel:

• Method Name: DrawTopHeader
• Parameters: g As Graphics

And type the following code in the associated Code Editor:

Const kPDFDocumentHeader As String = "PDFDocument"

DrawUpperBand(g, 0, 50)

g.FontName = "Helvetica"
g.FontSize = 180
g.Bold = True

Var x As Double = g.Width / 2 - g.TextWidth(kPDFDocumentHeader) / 2
Var y As Double = 220

g.DrawingColor = &cC9F2C900
g.DrawText(kPDFDocumentHeader, x + 4, 224)

g.DrawingColor = Color.Black

Static linearGradient As LinearGradientBrush

If linearGradient = Nil Then
  Lineargradient = New LinearGradientBrush
  linearGradient.StartPoint = New point(x, y - 224)
  linearGradient.EndPoint = New point(x, y)
  linearGradient.GradientStops.Add(New Pair(0.0, &c00BD4E00))
  linearGradient.GradientStops.Add(New Pair(0.7, &c00FD1F00))
  linearGradient.GradientStops.Add(New Pair(1.0, &c25712900))
End If

g.Brush = LinearGradient
g.DrawText(kPDFDocumentHeader, x, y)

As you can see, this is quite similar to the previous code. We are using a new Linear Gradient as the filling for the “PDFDocument” text. But first, it calls the DrawUpperBand method. This is a method that will draw a picture with a 50% opacity behind the header text, as well as the XDC logo in the lower left corner of the slide. Add a new method using the following values:

• Method Name: DrawUpperBand
• Parameters: g As Graphics, x As Integer, y As Integer

Type the following snippet of code in the associated Code Editor:

g.Transparency = 50.0
g.DrawPicture(UpperBand, x, y)
g.Transparency = 0
g.DrawPicture(XDC2x, 20, g.Height - XDC2x.Height)

Both “UpperBand” and “XDC2x” are PNG image files added to the project.

NextPage

Because the background and the header are common items in all the slides, we will render them every time we add a new slide (page) to the presentation (document). Create a new method using the following values:

• Method Name: NextPage
• Parameters: g As Graphics

And type the following lines of code:

g.NextPage(1920, 1080)
DrawPageBackground(g)
DrawTopHeader(g)

Creating the Content of the Slides

Now let’s add the method that will be responsible for adding the text of the main topic on every slide:

• Method Name: DrawTopic
• Parameters: g As Graphics, topic As String

And type the following code in the associated Code Editor:

Var x, y As Double
g.FontName = "Anoxic Light"
g.FontSize = 150

x = g.Width / 2 - g.TextWidth(topic) / 2
y = g.Height / 2 - g.TextHeight / 2

Static LinearGradient As LinearGradientBrush

If LinearGradient = Nil Then
  linearGradient = New LinearGradientBrush
  linearGradient.StartPoint = New Point(x, y)
  linearGradient.EndPoint = New Point(x, y - 80)
  linearGradient.GradientStops.Add(New pair(1.0, &c9FE1FF00))
  linearGradient.GradientStops.Add(New pair(0.0, &cF6F6F600))
End If

g.Brush = linearGradient
g.DrawText(topic, x, y)

Setting Transitions Between Slides

PDFDocument does support the range of transitions available under the PDF standard. In this case we are going to use the simplest: Fade. So, create a new method with the following values:

• Method Name: AddTransitions
• Parameters: d as PDFDocument

And type the following lines of code in the associated Code Editor:

// New PDFTransition instance, using the Fade style
// with one second of length.

Var t As New PDFTransition(PDFTransition.Styles.Fade, 1)

// And apply it on every page of the PDFDocument, starting on Page 2.
If d.PageCount > 2 Then
  For n As Integer = 2 To d.PageCount
    d.TransitionAt(n) = t
  Next
End If

Putting It All Together

Now we have all the pieces needed to create this small presentation in PDF. Go back to the Opening Event Handler and type the following lines of code below the last one:

DrawPageBackground(g)
DrawTopHeader(g)
DrawTopic(g, "First Slide")
NextPage(g)
DrawTopic(g, "Second Slide")
NextPage(g)
DrawTopic(g, "Third Slide")
NextPage(g)
DrawTopic(g, "Fourth Slide")

AddTransitions(d)

d.Save(SpecialFolder.Desktop.Child("Presentation.pdf"))

Done! Run the project and the PDF document will be saved to your computer Desktop. Once you open it in Adobe Reader, the app will detect that the document wants to use the full screen mode and, as soon as you confirm, it will begin the presentation. Depending on your preferences in Acrobat Reader, you may need to use the mouse button or arrow keys to change slides, or it may automatically advance to the next slide after the amount of time set.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Graphics Extensions

To start, and because we want to provide this ability to any graphic context, it makes sense to include all our logic in a Module. Let’s name it GraphicExtensions (as usual you can opt to use any other name). Start a new Xojo project and add a new Module to it using the following values in the Inspector Panel:

• Name: GraphicsExtensions

Next, and with the GraphicsExtensions item selected in the Navigator, add a new method to it using the following values in the associated Inspector Panel:

• Method Name: DrawText
• Parameters: Extends g As Graphics, value As String, x As Double, y As Double, wrap As Double, alignment As TextAlignments = TextAlignments.Left
• Scope: Global

As you can see, it nearly replicates the standard DrawText method from the Graphics class. Some things to note here, we are using the Extends keyword in combination with the first parameter to instruct the compiler that this method will “extend” the existing functionality of the Graphics class, so you’ll be able to invoke it using the usual dot notation on any instance created from the Graphics class.

The second thing is the last of the parameters “alignment As TextAlignments” TextAlignments is a global enumeration that we are going to use to learn the text alignment the user wants to apply to the block of text.

Next, type the following snippet of code in the associated Code Editor for the method:

#Pragma DisableBackgroundTasks
#Pragma DisableBoundsChecking
#Pragma NilObjectChecking False

value = value.ReplaceLineEndings(EndOfLine)

Select Case Alignment
  
Case TextAlignments.Default, TextAlignments.Left
  
  g.DrawText(value, x, y + g.TextHeight, wrap - x)
  
Case TextAlignments.Center, TextAlignments.Right
  
  Var tOutput() As String = PrepareOutput(g, value, wrap, x)
  
  Var tx, ty As Double
  ty = y + g.TextHeight
  
  Select Case Alignment
    
  Case TextAlignments.Center
    
    For Each s As String In tOutput
      
      tx = If(Wrap = 0, ((g.Width - Wrap) / 2 - g.TextWidth(s) / 2) + (x / 2), (wrap / 2 - g.TextWidth(s) / 2) + (x / 2))
      g.DrawText(s, tx, ty)
      ty = ty + g.TextHeight
      
      If ty > g.Height Then Exit
      
    Next
    
  Case TextAlignments.Right
    
    For Each s As String In tOutput
      
      tx = If(Wrap = 0, (g.Width - g.TextWidth(s)) + x / 2, (wrap - x) - g.TextWidth(s) + x)
      g.DrawText(s, tx, ty)
      ty = ty + g.TextHeight
      
      If ty > g.Height Then Exit
      
    Next
    
  End Select
  
End Select

As you can see, this code looks into the value of the Alignment parameter to see the approach to apply. If the Alignment equals to Default or Left we simply call the standard DrawText method on the received graphics context represented by the “g” variable. If not, we need to do some stuff to the received block of text to create the required chunks (or lines) that do fit the available width plus the received wrapping value. This is done in the PrepareOutput method.

Once we have all the lines with the apropiate widths in the Output array, then we only need to do some basic maths in order to calculate the final TX coordinate for every line, incrementing the TY coordinate on every new line to draw. As you can see, and in order to speed-up things a bit more, we check if the calculated TY coordinate is beyond the visible area of the graphic context and, if it is the case, we exit the function (it wouldn’t make much sense drawing text that is not going to be visible and whose processing consumes time).

Of course, the calculation of the TX and TY coordinates depends on the value of the Alignment parameter; that is, if the block of text is going to be drawn right aligned or centered.

Calculating Every Line Width

Now add the PreapareOutput method to the GraphicsExtensions module using the following values in the associated Inspector Panel:

• Method Name: PrepareOutput
• Parameters: g As Graphics, value As string, wrap As Double, x As Double
• Return Type: String()
• Scope: Private

And typing the following snippet of code in the associated Code Editor:

#Pragma DisableBoundsChecking
#Pragma DisableBackgroundTasks
#Pragma NilObjectChecking False

Var totalWidth As Double = If(wrap = 0, g.Width - x, wrap - x)

Var Input() As String = value.ToArray(EndOfLine)
Var output() As String

For Each s As String In Input
  
  If g.TextWidth(s) <= totalWidth Then
    output.Add(s)
  Else
    AdjustWidth(g, s, totalWidth, output)
  End If
  
Next

Return output

Once again, the first lines are some pragmas put in place to speed-up things, then the totalWidth variable will store the required maximum width value for every line. The Input array is going to store every paragraph from the source text, while the Output array will store every processed line and, the one returned to the method calling PrepareOutput.

Then we need to iterate every entry in the Input array and check if its width meets the totalWidth requirement. If it does, then that entry will be added to the Output array; if not, we still need to split the “paragraph” into as many chunks of text as needed that meet the expected maximum width. That is something that’s going to be done by the AdjustWidth method.

Splitting Chunks of Text … Recursively

Add the third, and last required, method to the GraphicExtensions module using the following values in the associated Inspector Panel:

• Method Name: AdjustWidth
• Parameters: g As Graphics, s As String, width As Double, ByRef output() As String
• Scope: Private

Next, type the following lines of code in the associated Code Editor:

#Pragma DisableBoundsChecking
#Pragma DisableBackgroundTasks
#Pragma NilObjectChecking False

Var n As Integer

If g.TextWidth(s) <= width Then
  output.Add(s)
Else
  
  // This can be improved pre-calculating the initial value for "n"… so it's
  // left as an exercise for the reader :-)
  
  While round(g.TextWidth(s.Left(s.Length - n))) > width
    n = n + 1
  Wend
  
  output.Add(s.Left(s.Length - n))
  
  AdjustWidth(g, s.Right(n), width, output)
  
End If

As you can see, if the width of the received string is less than or equal to the expected width, then it is added to the Output array. If not, we are using a really less than optimal technique to calculate the appropriate one, saving the resulting string to the Output array and passing the remaining of the string again to the method. You’ll probably want to change some things here to better pre-calculate the initial value of the n variable.

Testing It

We have everything in place, so let’s test it! Start by adding a new constant to the Window1 window and name it kSampleText. Use the associated Inspector Panel to assign the block of text you want to use for testing (personally I like to use the https://www.lipsum.com website for getting sample text).

If you prefer, you can download the complete Example project from this link.

Add next the Opening Event Handler to the Window1 window and type following snippet of code in the associated Code Editor:

Var p As New Picture(612, 792)
Var d As New PDFDocument

Var g As Graphics = p.Graphics
g.FontName = "Helvetica"
Var gPDF As Graphics = d.Graphics

g.DrawText(kSampleText, 40, 10, 570, TextAlignments.Right)
gPDF.DrawText(kSampleText, 40, 10, 570, TextAlignments.Right)

Var tH As Double = g.TextHeight(kSampleText, 570) + g.TextHeight * 4
Var tPH As Double = gPDF.TextHeight(kSampleText, 570) + gPDF.TextHeight * 4

g.DrawText(kSampleText, 40, th, 570, TextAlignments.Center)
gPDF.DrawText(kSampleText, 40, tPh, 570, TextAlignments.Center)

CustomDesktopCanvas1.Image = p
d.Save(SpecialFolder.Desktop.Child("PDFTextAlignment.pdf"))

As you can see, I chose the “Helvetica” font, but you can change it to any font that is available in your OS. The point here is that we are feeding our “extended” DrawText method with the sample text and the alignment we want to use in for drawing it both in the graphic context of a Picture and the one from a PDFDocument instance. Also, CustomDesktopCanvas1 is a simple Canvas subclass with an “image” property added to it as a computed property, so when a new value is assigned it will refresh itself and the Paint event will draw the picture centered in the canvas.

Run the example project and you should see something similar to the result displayed in the screenshots. Of course, there are still some details to take care of, for example when a line is split so the last letter goes over to the next line and things like that but, as mentioned in the beginning of this post, this is just a starting point. Adapt and improve upon it as needed.

Have fun!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Once the document has been signed and saved to disk, anyone opening the document will be able to check if the signature on the document is still valid or if, on the contrary, there have been changes to the documents after it was signed.

Adding signing controls to a PDF Document with this code:

Var d As New PDFDocument

// Creating a new PDFSignature instance
Var signatureField As PDFSignature = New PDFSignature(1, X, Y, Width, Height, "SignatureField")

// …and adding it to the Form controls in the PDFDocument instance
d.AddControl(signatureField)

As you can see, you need to create a new instance from the PDFSignature class providing to the Constructor method the page number, X and Y coordinates, and the width and height values for the interactive signing box.

These screenshots show a PDF document with a PDFSignature control added before it has been signed (on the left), and after it has been signed using a Digital Certificate (on the right). The project that produced the example below is included in the Example Projects folder in the Xojo download.

Lastly, and as it happens with many other features of the PDF format specification, the ability to digitally sign the PDF documents created with the PDFDocument class is up to the PDF viewer you use. For example, the free app Adobe Acrobat Reader does support this feature, while that is not the case with the Preview app provided by macOS.

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

As you probably know, the best way to stay in the “safe zone” when using fonts in your PDF files is to use only the Standard 14 fonts: Helvetica, Times, Courier, Zapf Dingbats and Symbol. As part of the PDF standard, these fonts are as close to a “guarantee” that the operating system will display the text correctly without needing to embed any fonts as part of the PDF file. As result, the PDF files are smaller when you use on the Standard 14.

But, of course, there are times you need to include more visually captivating fonts in your PDF documents. In these cases, you can use fonts that are already available (installed) in the Fonts folder on the OS. But if you want to use fonts that aren’t available by default to the Operating System, PDFDocument has improved in this regard in Xojo 2022r1.

First, the fonts cache manager has been improved for speed, decreasing the time required to access and get the font data even when it’s the first time to be used in text drawing on the PDF document. But not all Operating Systems include the fonts required by the PDF Standard 14, and PDFDocument requires that any font you want to use be installed in the computer/device (or added using AddFonts). Follow these tips:

• macOS includes by default all the fonts required by the PDF Standard 14, except Monterrey. Where Times is not installed you can use Times New Roman.
• Windows doesn’t includes Helvetica, Times, Courier or ZapfDingbats. You can use Arial, Times New Roman, Courier New and install ZapfDingbats or any similar font you want to use.
• Linux doesn’t includes any of the Standard 14 fonts, but you can use some that are equivalent and are installed by default in most of the Linux distributions: Liberation Sans instead of Helvetica, Liberation Serif instead of Times and Liberation Mono instead of Courier. You can install the Symbol and ZapfDingabts font files or any that is equivalent to these.

In addition, it is typical for Linux based servers not to have many fonts installed; make sure to install all the font files you intend to use in the creation of your PDF documents.

Embedding the Fonts in the PDF

On the other hand, and because this was a feature requested by several users, we have brought back the EmbeddedFonts property (set by default to False). This way, when you use any font not included among the Standard 14 ones, the data of that fonts won’t be included either as part of the PDF contents, resulting, thus, in smaller PDF files.

This feature is especially useful for sharing PDFs with people that have the same set of fonts installed in their OSs, as it is the case in many companies. Additionally, using EmbeddedFonts can considerably reduce the size of the PDFs.

But if the PDF documents created this way are distributed for public or general use, then the end user won’t have the exact same set of fonts used during the creation of the PDF and, as result, those not available fonts will be substituted and the text won’t render as expected or was initially designed to (including fonts metrics and styles).

If, on the contrary, the EmbeddedFonts is set to True, then the PDF document will include all the required font information (excluding the data for those in the Standard 14 set) in order to render properly the text, both if the user has those fonts installed or not.

Using Fonts Not Installed in the Operating System

The PDFDocument.AddFonts method has been generally improved and now includes the ability to use fonts not installed when creating PDF Documents in iOS apps created with Xojo.

In this example, I recommend setting the PDFDocument.AddFonts property to True in order to guarantee that the required font data is included as part of the PDF document itself.

Take into consideration the following:

1. While using external fonts on Windows– Provide AddFonts with a FolderItem pointing to the directory containing the font files.
2. While using external fonts on macOS– macOS requires copying to the Resources > Fonts folder, inside the app bundle, for any font you want to use that is not among those available in the Fonts folder. To do this, add a “Copy Files” compilation step to your Xojo project, copying all the fonts you are going to use inside the “Fonts” subdirectory and select “Resources” as the option in the “Destination” entry form the Inspector Panel. In addition, add a text file to the project in the Xojo Navigator (for example named “ExtraKeys.plist”) with the following text:

   <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd"> <plist version="0.9"> <dict> <key>ATSApplicationFontsPath</key> <string>Fonts</string> </dict> </plist>

3. While using external fonts on iOS– As it is the case with macOS, iOS requires copying any fonts you want to use in your PDF and that aren’t already installed to the “App Parent Folder”. To do this, add a “Copy Files” compilation step to your Xojo project, copying all the font files inside the “Fonts” subdirectory, and selecting “App Parent Folder” as the Destination in the associated Inspector Panel. In addition, add a text file to your Xojo project (for example named “iOSKeys.plist”) whose content will be similar to this:

   <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>UIAppFonts</key> <array> <string>Honey.ttf</string> <string>Montserrat-Regular.otf</string> <string>Gypsum.ttf</string> </array> </dict> </plist>Notice how, in this example, the "Honey.ttf", "Montserrat-Regular.otf" and "Gypsum.ttf" entries are the name of the font files that will be added to the iOS app using the Copy Files compilation step. You'll need to change that names for the font files you're going to use (including the file extension) and make sure that the ".plist" file has as many of these entries as the amount of fonts added to the project using the Copy files compilation step.

   

   For example, this screenshot shows a PDF created on iOS that uses the fonts named in the previous “.plist” file.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

With Xojo 2022r1 I am happy to say we have achieved that goal! The best part is that you don’t need to do anything to take advantage of the update. Keep your code as it is now and, the next time you output your report into a PDF document you’ll get the full vectorial quality you expect!

As you can see, the difference is quite notable. Additionally, because the new Reports rendering is full vectorial quality, that means that you will be able to select the text or even using the Search capability provided by your PDF viewer app.

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

Fillings and Drawing with Brush

The Brush property allows you to assign, well, a brush to the current Graphics context in order to use it as the drawing color or filling for any of the available shapes when drawing text and also in drawing vectorial paths into the PDF document. When the Brush property is set to Nil, then the color set via DrawingColor will be applied.

What makes the Brush property especially interesting is that you can assign to it any instance created from the PictureBrush, LinearGradientBrush or RadialGradientBrush classes.

• PictureBrush. PDFGraphics only supports the Tile, so the picture will be repeated until completing the filling area.
• LinearGradientBrush. PDFGraphics offers the same support you expect when it is used in combination with the regular Graphics class.
• RadialGradientBrush. PDFGraphics offers the same support you expect when it is used in combination with the regular Graphics class.

The following image shows a PDF with PictureBrush applied as the color for the text, RadialGradientBrush set to fill the lower rectangle, and also as the outline color for drawing the “The Golden” text. Additionally, a LinearGradientBrush is used to fill the upper rectangle. The graphic context has been set to use a transparency value when drawing the text, so it also affect the transparency of the filling brush on these.

ClipToPath

In opposition to ClipToRectangle or Clip, the ClipToPath method allows the definition of a irregular area that will act as the cropping area for any later drawing in the PDF, while ClipToRectangle and Clip provide regular areas: rectangles or squares.

When used in combination with PDFGraphics , expect the same behavior as when used in combination with a regular context from the Graphics class. For example, while the following snippet of code will draw a circle, only the portion contained in the ClipToPath set will be visible (a triangle), as you can see in the picture below from the generated PDF.

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: New Graphic Contexts

In opposition to ClipToRectangle and ClipToPath, the Clip method is more powerful because it not only provides a cropping area but a fully new Graphic context. That is, you’ll be able to set any of the properties on the returned Graphics.Clip context and also call any of the PDFGraphics supported methods on it.

In this regard, all the coordinates provided for the drawing are relative to the top/left of the new Clip, and not on the main Graphics context it is based on. So, if we run the following snippet of code:

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)

We can see how the line of code g1.DrawTex "…World!", 0, 0 provides 0,0 as the X and Y coordinates for drawing the text. That is, the top/left origin of the created clip, while these values would be 40,130 as absolute coordinates if we had used the main graphics context.

The PDF generated as result of the previous code is the one shown in the following picture:

Of course, you can nest as many Clips as you need. For example you can create a new Clip from a previous clip created in a previous step.

DrawObject

PDFGraphics also allows you to draw any of the objects created as instances from any of the Object2D class, and also those under the hierarchy of a Group2D object:

• ArchShape
• CurveShape
• FigureShape
• OvalShape
• PixmapShape
• RectShape
• RoundRectShape
• TextShape

For example, the following snippet of code will create the PDF document you can see in the picture.:

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"))

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

With 2021r3 you’ll be able to effectively set and use both Transparency and also the Color alpha component in any item you add to PDF documents: text, shapes and images! Moreover, the support of the Pictures has been improved so PDFDocument will work with the alpha channel of the image, instead of considering the alpha channel of the image as a fixed white background as in previous releases. That means more flexibility in the layout of the PDFs!

And because Transparency support is added to PDF using the Graphic class you, the way to use it is very straightforward. For example, put this following snippet of code in the Open Event Handler for a Desktop project (in this case, the referenced “GrassBG” picture has been added to the project):

// Creating a new PDFDocument instance
Var d As New PDFDocument

// Getting the graphic context from the PDF Document
Var g As Graphics = d.Graphics

// How many rectangles fits in the page width?
Var iter As Integer = g.Width/10

Var x As Integer

// Let's calculate the Y coordinate for center the
// GrassBG in the height of the PDF page
Var imageY As Integer = g.Height/2 - grassBG.Height/2

// And calculate the Y coordinate for drawing the rectangles
Var y As Integer = (imagey + grassbg.Height) - 40

// Transparency value = 0
Var tLevel As Integer

// Value to increase the Transparency on every rectangle
// drawing step
Var offset As Integer = 10

Var txt As String = "Transparency"

g.FontSize = 90
g.Bold = True

// X and Y coordinates to center the "Transparency" text
// on the page width / height
Var txtX As Integer =  g.Width/2 - g.TextWidth(txt) / 2
Var txtY As Integer = ImageY + GrassBG.Height - g.FontAscent

// Drawing the "Transparency" text -> Background layer!
g.DrawText txt, txtX, txty

// Drawing the GrassBG picture over the text
// that's the second layer, and preserving
// the PNG alpha channel
g.DrawPicture grassBG,0,ImageY

// Setting the initial random color for drawing
// the first rectangle
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

// Drawing the horizontal strip of rectangles.
// This is the third layer
For n As Integer = 0 To iter

  // Setting the Transparency value
  g.Transparency = tLevel

  // Drawing the rectangle
  g.FillRectangle x,y,20,40

  // Assign the current Transparency value to
  // tmpLevel variable in order to draw the color drops

  tmpLevel = tLevel

  // Y coordinate for the color drop
  y1 = y + 40

  // Drawing the color drops for the current Rect
  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

  // We increase the X coordinate for drawing the
  // next rectangle
  x = x + 20

  //…and increase the Transparency value by ten
  tLevel = tLevel + offset

  // we reached the maximum allowable value for
  // the transparency, so let's invert the sign
  // for the offset and set a new
  // drawing color.
  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

// Let's draw the fourth layer over the strip of rectangles
// with the "Comes to PDFDocument" text.
txt = "COMES TO PDFDOCUMENT"
g.FontSize = 30

// Notice that we are setting here the alpha value for
// the color, instead of relying on the Transparency property
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

// Getting a FolderItem reference pointing to the
// "Transparency.PDF" file on the desktop.
Var f As FolderItem = SpecialFolder.Desktop.Child("Transparency.pdf")

// Saving the PDFDocument file
d.Save(f)
f.Open

Once you run this code, it will produce the PDF with the image as it is shown at the top of this post.

As you can see, there are four layers to this document with the “Transparency” text drawn in the first layer (the farthest back), followed by a PNG image whose alpha channel lets us see the non-covered portions of the text behind it.

Next, the image is followed by a strip of horizontal rectangles in a new layer over it, that is drawn using a variable amount of transparency.

Finally, in the frontmost layer, we are drawing the “Comes to PDFDocument” text making use of the alpha value in the White color set as the DrawingColor.

You can see how the two upper layers mixed their color / level of transparency against the ones behind them and, of course, the text drawn in the PDF document continues to be vectorial and editable.

Transparency vs. Color’s Alpha Value

As you probably already know, the Transparency value can range from 0.0 (opaque) to 100.0 (fully transparent), while the alpha component of a Color instance can range from 0.0 (opaque) to 255.0 (fully transparent).

What happen when you use both kind of values in the drawings of your PDF document? Let’s suppose you did set a Transparency value of 40 while setting the alpha value of the current drawing color to 127. In that case, the alpha value of the drawing color offers a higher transparency, so that will be the value applied in the drawing (because all kind of drawings, except Pictures, are affected by the current drawing color).

Otherwise, if the Transparency value is higher than the alpha value of the current drawing color, then that will be the level of transparency applied to the drawings and, in this case, also affecting to the Pictures in the PDF document.

Learn more about PDFDocument in the Xojo Documentation. And watch this 7 minute video tutorial that demonstrates this handy new feature!

• PDFButton
• PDFTextField
• PDFTextArea
• PDFCheckBox
• PDFRadioButton
• PDFPopupMenu
• PDFComboBox
• PDFListBox

As defined by the PDF Standard, it is only possible to add one Form to a PDF document. Also, when any of these controls are added to a PDF document they won’t provide any visual cue in the actionable area itself. This means that it is up to you to “draw” any desired visual cues, for example a rectangle or rounded rectangle surrounding a Button, TextField or TexArea control, or the text labels you want to associate with CheckBoxes or RadioButtons.

For example, this is how a TextField would appear when added to a page:

As you can see, it only displays the actionable area plus the text assigned as the default value set to this PDFTextField instance.

And this is how it looks with a rectangle added using the Graphics.DrawRectangle method:

The way to add any of these Form controls to a PDFDocument instance is quite simple; call the AddControl method in the PDFDocument instance passing along any of the supported PDF control instances.

About the behavior of these controls, it is worth mentioning the following cases.

PDFButton

You can add new instances to the Form based on this class to get the following Actions:

• PDFButton.Actions.ResetAction resets the controls added to the form to their default values (if any)
• PDFButton.Actions.SendForm sends the values entered/selected by the user in the Form controls as a series of Key/Value pairs, where the Key is the name of the control, and the value sent is the entered/selected value. This data will be sent to the URL endpoint set to the URL property of the PDFButton instance. For example, a valid URL could be “http://127.0.0.1:8080”, “https://myDomain.com/WebService” or “mailto://someEmailAddress@here.com”. If the URL is a “mailto:”, then the receiver will get these values as a text file attached to the email message itself.
• PDFButton.Actions.SendPDFFile the endpoint url will receive the PDF file itself both when using a “mailto:” or “http(s)//” protocol.

It is very important to note that not all the PDF viewer apps support these actions. For example, the Preview app on macOS doesn’t support them. So it is advisable to use the free Adobe Acrobat Reader DC available on every operating system.

PDFRadioButton

You can add PDFRadio button to the PDF form as an individual button or as a group. When it is added as an individual RadioButton it is only possible to select/deselect it, while when used as a RadioButton group, the activation of any of the RadioButtons will disable the other RadioButtons in the group. 

The way to configure a RadioButton instance as a member of a group is by using the same name. For example, the following code:

Var rBtn1GroupA As New PDFRadioButton(1, 200, 450, 15,15,"GroupA","OptionA")
Var rBtn2GroupA As New PDFRadioButton(1, 200, 470, 15, 15,"GroupA", "OptionB")
rBtn2GroupA.Value = True
d.AddControl(rBtn1GroupA)
d.AddControl(rBtn2GroupA)

This will create two PDFRadioButton instances named rBtn1GroupA and rBtn2Group2 sharing the same name “GroupA” but using different values: “OptionA” and “OptionB”. Also, the rBtn2GroupA instance is set as the default RadioButton:

rBtn2GroupA.Value = True

Because it is only possible to create one Form per PDF document, it doesn’t matter that the RadioButton instances pertaining to a same group are in all the PDF document pages; they will continue behaving as members of the same group.

PDFPopupMenu and PDFComboBox

These controls behave similar to what you expect in any Xojo project. You can populate them with a series of default options and set one of them as the selected option displayed by default. The main difference is that a PDFComboBox lets the user type text that is not available among the assigned options.

For example, the following fragment of code will create a PDFPopupMenu instance:

Var cPopup As New PDFPopupMenu(1,210,540,100,15,"List","Option A", "Option B", "Option C", "Option D")
d.AddControl(cPopup)

Here “List” is the name of the control itself and “Option A”, “Option B”, “Option C” and “Option D” are the values that will be presented as the menu options to the user.

Of course you can also pass along the PDFPopupMenu options as a String Array to the Constructor if you want:

Var r() As String = Array("Option A", "Option B", "Option C", "Option D")
Var cPopup As New PDFPopupMenu(1,210,540,100,15,"List",r)
d.AddControl(cPopup)

Creating a PDFComboBox instance is similar. For example:

Var cCombo As New PDFComboBox(1,100,540,100,15,"ListC","Option A", "Option B", "Option C", "Option D")
cCombo.SelectedRowValue = "Option C"
d.AddControl(cCombo)

In this case, “Option C” will be the value selected by default.

PDFListBox

There is not much difference about how the PDFListBox instances are created, when compared with a PDFPopupMenu or PDFComboBox:

Var options() As String = Array("Option A", "Option B", "Option C", "Option D")
Var cListBox As New PDFListBox(1,320,540,100,90,"ListB", options)
cListBox.RowSelectionType = PDFListBox.RowSelectionTypes.Multiple
cListBox.SelectedRowValue = "Option D"
d.AddControl(cListBox)

As you can see, in this case the value selected by default will be “Option D”. The main difference is that a PDFListBox allows you to set the RowSelectionType between “Multiple” and “Single” as is the case when using the DesktopListBox in a regular Xojo project. So, in this case, you can tell the cListBox instance to allow the user to select multiple entries in the control:

cListBox.RowSelectionType = PDFListBox.RowSelectionTypes.Multiple

One thing to note is that when the PDF is sent to an endpoint URL using the SendForm kind of Action, multiple options will be represented as a repeated series of Key/Value pairs with the same Key name. For example, let’s say that the user selects the “Option B”, “Option C” and “Option D” values. Then, the endpoint webservice will receive:

ListB=Option+B&ListB=Option+C&ListB=Option+D

Notice how in all these cases “ListB” is the same name given to our PDFListBox instance.

PDFTextField and PDFTextArea

There are a couple of interesting properties you can set on the instances created from these classes:

• ReadOnly: Set this property to True so the user can’t type on the control.
• MaximumCharactersAllowed: Set this property to the maximum number of characters that the user is allowed to type in the control.

This fragment of code will create a PDFTextField instance:

Var tf As New PDFTextField(1, 100, 50, 200, 22, "TextField", "Some sample text")
d.AddControl(tf)

“TextField” is the name of the control instance, and “Some sample Text” is the displayed default value.

And this is how we can create a PDFTextArea instance setting the maximum of allowed characters to 100:

Var ta As New PDFTextArea(1, 100, 100, 200, 300, "TextArea", "Hi There!")
ta.MaximumCharactersAllowed = 100
d.AddControl(ta)

“TextArea” is the name of the control instance and “Hi There!” is the displayed by default value.

Summary

Now you can see how easy it is to add Forms to your PDF documents created with Xojo! If you want to learn more about how these work and also play with the different Action modes, you can run the PDFFormTest-Desktop Xojo project found in the Example Projects > PDF folder and see the Xojo Documentation.

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

With Xojo 2021r3 we are handling the images added to PDFDocument in a different way. When images are added to the page using a smaller size than the original size, which is probably more common, using something like:

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

g.DrawPicture myImage, 10, 10, 100, 100, 0, 0, myImage.Width, myImage.Height

or

g.DrawPicture myImage, 10, 10, myImage.Width/3, myImage.Width/3, 0, 0, myImage.Width, myImage.Height

“myImage” being an image added to the Xojo project, loaded from disk or from a database query.

You can appreciate how the quality has improved from left to right, below.

Also, the new way the image PDF streams are created in order to get this sharpness means that all the data of the source image is added to the PDF document. In other words, it will increase its size. Comparing the same document, the one created with Xojo 2021r2.1 is 521 KB, and the one created with Xojo 2021r3 is 3.1 MB. This is because adding the full size of the the image takes a total of 950 KB, plus support for alpha and masks…

But the good side of the extra document size is that, because images are embedded at their full resolution, they will keep looking sharp even when the PDF document is displayed beyond 100% its original scale. You can see in the PDF document below created with Xojo 2021r2.1:

And the PDF document created with Xojo 2021r3:

Document Size vs Image Quality

The winner of this battle depends what do you want to offer to your users. Using our example document we have the following figures:

• PDF document resolution (w x h): 612 x 792 pixels
• The apple image resolution (w x h): 607 x 576 pixels

As you can see, the apple image has nearly the same resolution that the full page of the PDF Document! But it is rendered at a final size of 100 x 100 pixels. That means that the image will keep sharper even if we use a zoom value of 800% in the viewer app, but that has a cost in the size of the generated PDF document.

You’ll probably want to keep the images added to the PDFDocument pages at a maximum of twice the final width and height. That will produce good looking images in your PDF documents while keeping the document to a reasonable size. Learn more about PDFDocument and what’s new in the Xojo Documentation.

For Storage

Sure, you can save a PDF created from a PDFDocument instance, as a file or to a database as a binary blob; but you’ll probably save a bunch of bytes if you save the JSON representation of the PDF document provided by the PDFDocument.Template method.

Let’s suppose you want to save these as simple “templates” for your app’s/solutions purposes. The main difference is that if you save these as PDF files, you won’t be able to add new objects / drawing / text or anything PDF-related to them because PDFDocument can’t parse or recreate the required objects from the data streams in the PDF file, so they won’t be able to continue to work with these.

On the contrary, if you save these “templates” to a file or Database using the Template method, you’ll later be able to create a new PDFDocument instance. All you need to do is pass along the saved JSON data to the PDFDocument constructor and voilà! Now you can continue adding new stuff to that new PDFDocument instance: from text to shapes, images, forms or new pages- anything that is supported by PDFDocument.

Because you don’t want to draw all the stuff again

A new PDFDocument instance created from the data received through the Template method means that there is not need to “draw” the PDF again from scratch using Xojo code. The PDFDocument constructor will take care of the all the needed steps in order to recreate the required objects from the received data.

You may think, “Well, my app already has the code needed to draw that same PDF documents”. Maybe that’s true for some scenarios, but not for all.

For example, what about a solution whose main app is in charge of drawing these base PDF documents or “templates” via code, later saving them to a database? Then, the client app will be able to simply get the PDF “template” they need from the database, create a new PDFDocument instance from that data, and add all the new stuff they need … without relying in the code that was needed to create the base PDF document in first place.

You want to offer a visual PDF Editor to your users

Maybe you are thinking about offering your users a visual editor so they can create PDF documents by simply dragging and dropping controls from a panel, just as you do when working with the Layout Editor in the Xojo IDE.

In this case, it is really worth offering your users an option so they can save the PDF document in its current state for a later retrieval; like you would expect from any editor out there in 2021. In that case, and thanks to the PDFDocument.Template method, that is quite easy! Call the method on the PDFDocument instance and save the retrieved JSON data in the file format or database engine you want.

Your users will be able to run your app again a few hours or days, retrieve any of the PDF documents they previously saved and continue working on them in the same point they left!

Quick Example: Working With PDFDocument.Template

Let’s put this feature in practice with a simple example. This example isn’t that useful for a real-world app, but it serves to demonstrate well how PDFDocument.Template works.

So, let’s start with a code snippet that will create a really simple PDFDocument; just some text and a circle in a one-page document:

Var d As New PDFDocument

Var g As Graphics = d.Graphics

g.FontSize = 30
g.DrawText "Hello there!", 50, 100

Var x, y As Double

x = g.Width/2 - 100
y = g.Height/2 - 100

g.DrawingColor = Color.Red
g.Transparency = 50.0

g.FillOval(x,y,200,200)

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

This is the how that PDF document will look; not too impressive, but it works for the example purpose:

Now let’s add a line of code to get the “template” data from that document:

Var template As JSONItem = d.Template

And this is how the JSON data will look for that document:

{"General":{"Author":"","Creator":"Xojo","Keywords":"","Subject":"","Title":""},"Document":{"Compression":true,"EmbeddedFonts":false,"Landscape":false,"Width":612.0,"Height":792.0},"Actions":{"0":{"FontSize":"30.00"},"1":{"DrawText":"Hello there!,_ENDTEXT_,50.00,100.00,.00,False"},"2":{"Color":"&h00FF0000"},"3":{"Transparency":".50"},"4":{"FillOval":"206.00,296.00,200.00,200.00"}},"Images":{}}

A mere 396 bytes if we decide to save that data as text to a file. In comparison, our example PDF file is 1,380 bytes in length at this point.

Now let’s create a new PDFDocument instance from that template. All we need is to add this line to the existing code:

Var d2 As New PDFDocument(template)

And this is how it will look-like if we decide to save (and open) it:

Var f2 as FolderItem = SpecialFolder.Desktop.Child("SamplePDFFromTemplate.pdf")
d2.save(f2)
f2.Open

Not very surprisingly, we get the same PDF contents. After all, we created it from a … well … template.

The main point here is that we can continue working with the d2 instance, adding new stuff to it if we want to. Let’s change that second snippet of code a bit:

Var template As JSONItem = d.Template

Var d2 As New PDFDocument(template)
Var g2 As Graphics = d2.Graphics
g2.DrawText "Hi From The Template!", 50, 160

Some interesting things happen here. First of all, you didn’t need to set the font size because it is using the last FontSize value set in the original document where we got the Template data. That’s the same as the color used in drawing the text on the new PDFDocument instance- it is using the last DrawingColor set in the original document.

So, from this point on we can add anything we want to to our new PDFDocument created from the template! You may think about having the first snippet of code in one “main” app (the one we used to create the original PDF document plus the template data), and the second snippet of code only executed by your “client” apps (the one creating a second PDFDocument instance from the Template data).

Learn more about PDFDocument in the Xojo Documentation.

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

When we think about Table Of Content (TOC) entries, they can clearly be seen as a tree hierarchy where each branch denotes a deeper level hanging from a parent node.

In the above image, see how the “First Page” and “Second Page” entries in the TOC are at a root level for the first page and second pages in the document, respectively; while both “First Section” and “Second Section” are one level deeper, hanging from the root entry, and “First Sub-Section” is a third level deeper, hanging in this case from the “First Section” entry on the “First Page”.

How can we create this kind of TOC hierarchy in a PDFDocument? Using the PDFTOCEntry class in combination with the PDFDocument.AddTOCEntry method.

The PDFTOCEntry Constructor takes a total of four parameters:

• PageNumber As Integer. This is the page number of the PDFDocument instance that will be associated with the TOC entry. PDF pages start at 1.
• Title As String. The text that will be displayed as the title for the TOC entry in the PDF viewer.
• X As Integer. The X coordinate where the PDF viewer will jump in the associated page when the user clicks the TOC entry in the PDF viewer.
• Y As Integer. The Y coordinate where the PDF viewer will jump in the associated page when the user clicks the TOC entry in the PDF Viewer.

We will return a bit later to see how the “jump” to the X and Y coordinates behave in the PDF Viewer.

So, in order to create our first root TOC entry for the first page in a PDFDocument instance, all we need to do is:

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

Now, the “First Section” entry means that we want to add a Bookmark (or TOC entry) to the PDFDocument that, once the user clicks on it, will jump to a specific point (X/Y coordinates) in the same page; so we can create a new instance for it:

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

And the same thing for the first sub-section that will hang from the “First Section” entry:

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

So far, we have three PDFTOCEntry instances, but we still haven’t set any hierarchy among these. For that, use the PDFTOCEntry.AddEntry method. The following line of code will add the te1a instance as a sub-node on the te1 instance (that is, “First Sub-Section” as a node of “First Section”):

te1.AddEntry te1a

And now we can add the te1 instance as a sub-node of the te instance (that is “First Section” will be a sub-node of “First Page”):

te.AddEntry te1

Thus, in order to add a new section named “Second Section” also as a sub-node for the “First Page” root node, we only need to type the following lines of code:

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

You get the idea. I’m pretty sure you’ll know by now how to create the required instances and the associated hierarchy for the “Second Page” and “First Section” entries for the second page of the PDFDocument:

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

teG2.AddEntry teG2a

Lastly, all we need to do is add the root instances of the TOC hierarchy (that is te and teG2) to the PDFDocument instance itself. So, let’s guess that our PDFDocument instance is pointed by the d variable. In that case, these two lines of code will complete the Job:

d.AddTOCEntry te
d.AddTOCEntry teG2

TOC entries and PDF Viewer Behavior

PDF Viewer apps have their own rules about how or when to “jump” to the X / Y coordinates associated with the TOC entries. In brief:

• If the target coordinates for the target page are already in the view area, then you won’t notice anything. After all you are already seeying the contents of the page that the X / Y coordinates are pointing to! For example, this may be the case when you set the PDF Viewer app to display the two pages of the PDF document at once in the view.
• If the target coordinates for the target page are out of the view area, then the PDF viewer will jump to the specified coordinates putting its contents in the view. The behavior in this case depends on the zoom factor you may be using for displaying the page. That is, it is possible you can see the how the PDF viewer “jumps” to the second page when you click on the “Second Page” entry in the TOC, putting its contents in the view area, but not if you click on the “First Section” or “First Sub-Section” entries for the first page in the document if that page is already in the view area and the zoom is set to “Fit Contents to Window”.

Summary

As we have seen, it is quite simple to create a Table of Contents index for your Xojo PDF documents, adding as many entries as the structure of your PDFs need, in order to provide a better document navigation! Read more about PDFDocument in the Xojo Documentation.

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.