Like other controls in the Xojo framework, DesktopGrid is a data-source-based control. Instead of manually adding cells, rows, or columns as you would with a ListBox, the DesktopGrid itself requests the data it needs when it needs it. This approach brings several benefits:

ContainerControl-based cells: The cells in a DesktopGrid are full ContainerControls, just like the ones you’re already familiar with. You can use the same layout for all cells or customize different layouts for individual cells, rows, or columns. Each cell represents a live control and behaves accordingly.

• Lower memory footprint: DesktopGrid keeps only the cells that are currently visible on screen “alive,” which significantly reduces memory usage, especially when working with very large data sets. For example, when you resize the containing window, the DesktopGrid will request additional content from its DataSource only if necessary. When cells move outside the visible area of the DesktopGrid, their corresponding ContainerControl instances are “closed,” triggering an event you can handle, and freeing the memory they were using.
• Faster execution: Large data sets are not preloaded into the control. This means that opening a window with a DesktopGrid or running an app with many cells happens almost instantly, providing a smooth and responsive experience even with extensive data.

• Layout Flexibility: Since the number of rows and columns is determined by the DataSource, a DesktopGrid instance can have a flexible layout rather than a rigid, static one. For example, you can adjust the number of columns based on the available width of the DesktopGrid. You can also set different widths for individual columns, while the row height remains fixed.

• Data representation changes “on the fly”: Because the DataSource provides the content for each cell, you can dynamically change the data representation (the ContainerControl layout) at runtime or even pull data from a completely different source.
• A better separation of responsibilities: While you can implement the GridDataSource interface directly on the DesktopGrid or in its containing Window, using a dedicated DataSource class is the cleaner approach. This ensures a clearer separation between the view (the DesktopGrid), the model (the data feeding the cells), and the controller (which manages interactions between the two). A single DataSource can also feed multiple DesktopGrid instances, making your code more reusable.
• Headers everywhere: By default, DesktopGrid displays column and row headers. You can modify this in the Inspector Panel or via code. Depending on your scenario, you might choose to show both headers, just one, or hide them entirely. By default, the headers display simple numbering for each column and row. However, you can fully customize their content using the PaintHeaderContentForColumn and PaintHeaderContentForRow methods of your GridDataSource implementation, giving you complete control over how headers appear.

Is the DesktopGrid a replacement for DesktopListBox?

While you can use DesktopGrid for many purposes, it is not a direct replacement for DesktopListBox in all scenarios. If your data is primarily textual (like simple labels) or relies on features specific to DesktopListBox, such as hierarchical data representation, then DesktopListBox is still the better choice.

DesktopGrid shines in scenarios where you need complex layouts in each cell using live controls rather than temporary pictures or workarounds. Each cell can have its own layout, including interactive controls such as ListBoxes, buttons, or other reactive elements that respond to user interactions. This makes DesktopGrid ideal for rich, interactive, and highly customizable grid layouts.

Performance Caveats to Consider

Although the first iteration of DesktopGrid was designed with performance in mind, there are some factors that may affect its redraw speed. The most significant is that each cell uses live controls, so performance will be similar to placing the same number of controls directly on a Window. While alternative approaches—such as reusable cells or backing picture representations—could improve speed, they come with their own trade-offs.

As a general rule, performance depends on cell size and the number of visible cells at any given time. A large DesktopGrid with many rows and columns, even if each cell contains just a simple label, may experience slower refresh rates. Additionally, actual performance can vary depending on the operating system and its version, as these affect the underlying drawing and refresh processes.

Wiring the Grid

Although this is just the first iteration of the DesktopGrid control, we are already working on the next set of features while further refining the existing ones. You can read more about this control in the Xojo Documentation. We want to extend a big THANK YOU to everyone who provided feedback and dedicated their time testing the Grid during the beta cycle, you know who you are! Your input is invaluable, and the feature requests you submitted (combined with others already on our roadmap) will help shape a DesktopGrid that better fits your needs.

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

Let’s build a simple but incredibly powerful Desktop app: a threaded image resizer. This tool will let you pick a folder of images and resize them all without ever locking up the app. It’s a perfect showcase of how easy and effective threading can be in Xojo.

Let’s get started!

Step 1: Designing the User Interface

First things first, let’s lay out our app’s window. We’re going for a clean and simple design. All you need to do is create a new Xojo Desktop project and add the following controls from the Library onto your main window:

1. DesktopButton: This will be our “start” button. The user will click this to select a folder and begin the resizing process. Let’s set its Caption to “Select folder && Start”.
2. DesktopProgressBar: This will give the user visual feedback on the progress of the resizing operation.
3. DesktopLabel: We’ll use this label to display status updates, like which file is currently being processed or when the job is complete. Let’s call it StatusLabel.

Your app layout should look something like this:

Step 2: Adding the Magic Ingredient: The Thread

Now for the star of the show! Go to the Library and find the Thread object. Drag and drop one onto your window. By default, it might be named Thread1, but I’ve renamed mine to ResizeThread to make its purpose crystal clear. This object is where our background work will happen.

Quick note on thread types: Cooperative threads (the default) share a single CPU core with the main/UI thread and other cooperative threads. Preemptive threads can run on separate CPU cores and deliver true parallelism for CPU-bound work. More info on this subject: Cooperative to Preemptive: Weaving New Threads into your Apps

Why this project uses Preemptive threads: resizing many images is CPU-bound and benefits from parallel cores without blocking the UI.

Step 3: Kicking Off the Process

With the UI and thread in place, let’s add the code to get things moving. Double-click the “Select folder & Start” button to add its Pressed event. This is what will run when the user clicks it.

Here’s the code for the Pressed event:

' Ask the user for a source folder (contains images)
Var f As FolderItem = FolderItem.ShowSelectFolderDialog
If f = Nil Then Return ' user cancelled

mSourceFolder = f

' Reset UI
ProgressBar1.Value = 0
StatusLabel.Text = "Starting…"

' Kick off background work!
ResizeThread.Start

Let’s break this down. First, we ask the user to select a folder. If they don’t pick one, we simply exit. If they do, we store the selected folder in a window property called mSourceFolder (Public Property mSourceFolder As FolderItem). We then reset our progress bar and status label and, most importantly, we call ResizeThread.Start. That one simple line tells our thread to wake up and get to work by running its Run event.

Step 4: The Heavy Lifting (in the Background)

The Run event of the ResizeThread is where the core logic lives. This is where we’ll find, load, resize, and save the images. Remember, the golden rule of threads is: never touch the UI directly from the Run event. Doing so can cause crashes and unpredictable behavior.

Instead, we perform our task and then send a message back to the main thread with an update. We do this using a method called AddUserInterfaceUpdate.

Here’s the Run event code:

' Quick validation up-front
If mSourceFolder = Nil Or Not mSourceFolder.Exists Or Not mSourceFolder.IsFolder Then
  Me.AddUserInterfaceUpdate(New Dictionary("progress":0, "msg":"No folder selected"))
  Return
End If

Try
  ' Ensure output subfolder "<selected>/resized" exists
  Var outFolder As FolderItem = mSourceFolder.Child("resized")
  If Not outFolder.Exists Then outFolder.CreateFolder
  
  ' Build a list of candidate image files.
  ' Note: Using Picture.Open to validate images is simple and robust.
  '       (For very large folders, you could pre-filter by extension first.)
  Var images() As FolderItem
  For Each it As FolderItem In mSourceFolder.Children
    If it = Nil Or it.IsFolder Then Continue ' Ignore subfolders
    Try
      Var p As Picture = Picture.Open(it)
      If p <> Nil Then images.Add(it)
    Catch e As RuntimeException
      ' Non-image or unreadable; skip
    End Try
  Next
  
  Var total As Integer = images.Count
  If total = 0 Then
    Me.AddUserInterfaceUpdate(New Dictionary("progress":0, "msg":"No images found"))
    Return
  End If
  
  ' Resize settings (simple “fit within 800x800” bounding box)
  Const kMaxW As Double = 800.0
  Const kMaxH As Double = 800.0
  
  ' Short delay after each file so the main thread can repaint the UI
  Const kDelayMS As Integer = 50
  
  For i As Integer = 0 To total - 1
    Var src As FolderItem = images(i)
    Try
      ' Load source (immutable)
      Var pic As Picture = Picture.Open(src)
      If pic = Nil Or pic.Width <= 0 Or pic.Height <= 0 Then Continue
      
      ' Compute proportional scale (never upscale)
      Var sW As Double = kMaxW / pic.Width
      Var sH As Double = kMaxH / pic.Height
      Var scale As Double = Min(Min(sW, sH), 1.0)
      
      Var newW As Integer = Max(1, pic.Width * scale)
      Var newH As Integer = Max(1, pic.Height * scale)
      
      ' Render into a new mutable bitmap of the target size
      Var outPic As New Picture(newW, newH)
      outPic.Graphics.DrawPicture(pic, 0, 0, newW, newH, 0, 0, pic.Width, pic.Height)
      
      ' Build a safe base name (strip the last extension; handle dotfiles)
      Var name As String = src.Name
      Var ext As String = name.LastField(".")
      Var baseName As String
      If ext = name Then
        ' No dot in the name
        baseName = name
      Else
        baseName = name.Left(name.Length - ext.Length - 1)
      End If
      If baseName.Trim = "" Then baseName = "image"
      
      ' Save JPEG (fallback PNG if JPEG export not supported)
      Var outFile As FolderItem = outFolder.Child(baseName + "_resized.jpg")
      If Picture.IsExportFormatSupported(Picture.Formats.JPEG) Then
        outPic.Save(outFile, Picture.Formats.JPEG, Picture.QualityHigh) ' adjust the quality of the jpeg here
      Else
        outPic.Save(outFolder.Child(baseName + "_resized.png"), Picture.Formats.PNG)
      End If
      
    Catch io As IOException
      ' Likely a write/permission/disk issue; skip this file
    Catch u As UnsupportedOperationException
      ' Unsupported format/operation on this platform; skip
    End Try
    
    ' Progress + message to the UI (safe handoff)
    Var pct As Integer = ((i + 1) * 100) / total
    Me.AddUserInterfaceUpdate(New Dictionary("progress":pct, _
    "msg":"Resized " + src.Name + " (" + pct.ToString + "%)"))
    
    ' Let the main thread paint the update
    Me.Sleep(kDelayMS, True) ' wakeEarly=True allows early resume when idle
  Next
  
  ' Final UI message
  Me.AddUserInterfaceUpdate(New Dictionary("progress":100, "msg":"Done"))
  
Catch e As RuntimeException
  ' Any unexpected failure: report a friendly error
  Me.AddUserInterfaceUpdate(New Dictionary("progress":0, "msg":"Error: " + e.Message))
End Try

Step 5: Receiving Updates and Safely Changing the UI

So, how does the main thread “hear” these updates? Through the UserInterfaceUpdate event on the ResizeThread itself! This event fires on the main thread, making it the one and only safe place to update our controls.

Here’s the code for the UserInterfaceUpdate event:

' This event runs on the main thread – SAFE to update controls here.
If data.Count = 0 Then Return

Var latest As Dictionary = data(data.LastIndex)

If latest.HasKey("progress") Then ProgressBar1.Value = latest.Value("progress")
If latest.HasKey("msg") Then StatusLabel.Text = latest.Value("msg")

' A little bonus: when we are done, open the output folder!
If latest.HasKey("msg") And latest.Value("msg") = "Done" Then
  Var outFolder As FolderItem = mSourceFolder.Child("resized")
  If outFolder <> Nil And outFolder.Exists Then
    outFolder.Open
  End If
End If

In this event, we receive an array of Dictionaries (all the updates that have queued up). We usually only care about the very latest one, so we grab data(data.LastIndex). Then, we safely access the values from the dictionary and assign them to ProgressBar1.Value and StatusLabel.Text. That’s it!

Conclusion

And there you have it! A fully functional, non-blocking image resizer. By moving the heavy work to a Thread, we’ve created an application that provides a smooth, professional user experience.

The pattern is simple:

1. Start the task from the main thread (ResizeThread.Start).
2. Work inside the thread’s Run event.
3. Communicate back to the UI with AddUserInterfaceUpdate.
4. Update the UI safely in the UserInterfaceUpdate event.

That’s pretty much it! Go ahead, download this project’s source code from GitHub, play around with it, and think about how you can use threads in your own applications!

Happy coding!

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

Introducing the Xojo IDE for Linux ARM64

With the release of Xojo 2025r1, however, everything has changed. Now, for the first time, developers can run the Xojo IDE directly on their Raspberry Pi 64-bit device. This means you can write, build, and test your applications all from within the same environment. The seamless integration allows for faster iteration and a smoother workflow, giving you more control over your development process. Not only can you now run the Xojo IDE on a Pi, but also on any Linux ARM64 distro.

What is Supported?

Nearly all the features you love about working in the Xojo IDE on other platforms are now available with the Linux ARM64 IDE, with the exception of building macOS and Mobile (Android/iOS) apps. Instead of remotely debugging your Raspberry Pi app using the Xojo IDE on Windows, you can now remotely debug your Windows app using the Xojo IDE on Pi!

For best results, we recommend a Raspberry Pi 5 or 500 with 8GB of RAM.

Xojo Loves Pi!

With the Xojo IDE now available for Linux ARM64, we’re making our case as the go-to solution for Raspberry Pi developers. The simplicity, cross-platform support, and power makes Xojo an attractive choice for those looking to build apps on the Pi, without the complexity of traditional programming environments.

NOTE: You can build Linux apps with Xojo for free, no license required. Just select Linux in Build Settings, then choose ARM or x86 architecture in the Inspector.

William Yu grew up in Canada learning to program BASIC on a Vic-20. He is Xojo’s resident Windows and Linux engineer, among his many other skills. Some may say he has joined the dark side here in the USA, but he will always be a Canadian at heart.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Xojo plugins are add-ons that extend the functionality of the Xojo development environment, allowing developers to add additional features, integrate third-party libraries, and much more.

Write a Xojo Plugin

This article assumes familiarity with the Xojo Plugin SDK and focuses on automating plugin builds. If you’re new to plugin development, check out the resources in Xojo’s “Extras” folder, YouTube tutorials, and the Xojo Forum.

It builds on my previous blog post Xojo Github Actions and involves Docker, which has also been a part of a previous blog posts (Docker, Database Servers and Xojo, Running Xojo Web Applications in Docker). So read up there on what a GitHub Actions workflow is, what the .yaml files in the Folder .github/workflows are used for.

Build a Xojo Plugin

Since Xojo is a cross platform development environment, a Xojo plugin needs to be built for all the supported platforms (Windows, macOS, Linux) and all their architectures (Intel/ARM, 32/64Bit).

All the plugin parts (the Windows .dll‘s, .macOS .dylib‘s and Linux .so‘s) are being packaged into a .xojo_plugin file.

One of the challenges is to have an environment to build all that. At the first glance it seems that one would need a Mac, a Windows machine – as well as some Linux environment (any of which could also just be a virtual machine). And one would first think that there will be a lot of manual steps involved – building the plugin source on various machines, copying all the built plugin parts together to finally assemble the resulting .xojo_plugin.

However – all that is not required. You can build a Xojo plugin without your own machine being involved, fully automated. GitHub Actions provides all we need.

Example: CubeSQLPlugin

Let us have a look at this existing Open Source Plugin.

CubeSQLPlugin is an extension for the Xojo programming environment that allows developers to use CubeSQL, a fully featured and high performance relational database management system built on top of the SQLite database engine.

The plugin is being used in the Open Sourced Administrations Tools for CubeSQL, which are both written in Xojo: CubeSQL Web Admin and CubeSQL (Desktop) Admin.

Internally the plugin uses LibreSSL for TLS Connections of Database Clients to CubeSQL Server. This means that first the LibreSSL libs need to be built for all build targets. Only then can the plugin source be built again for all build targets. And finally, all the plugin parts need to be assembled into the Xojo plugin structure for the final .xojo_plugin.

We have automated the whole build process of the plugin using GitHub Actions by having created three workflows. You’ll find their source in the folder .github/workflows. All workflow executions you’ll find on GitHub in the tab named Actions (as long as they have not been deleted or removed).

LibreSSL
This workflow will download the LibreSSL Source, and build it for all needed build targets. It needs to be run only once, e.g. if a new LibreSSL version is available that should be included for the next plugin build. That’s why it’s a workflow that can be run manually. It asks which LibreSSL version should be built and whether the built libraries should be committed and pushed to the repository.

CubeSQLPlugin
This workflow will build the CubeSQL Xojo Plugin for all build targets using the currently committed LibreSSL libs in the repository. It will commit and push all the built .dll‘s, .dylib‘s and .so‘s to the repository.

Create Release
That one is pretty obvious, right? It builds the structure of the final .xojo_plugin and creates a new Release in the repository with the final Xojo plugin – ready to be downloaded.

Build for all Platforms and Architectures

The two workflows “LibreSSL” and “CubeSQLPlugin” are similar in their approach to building for all the supported platforms (Windows, macOS, Linux) and all their architectures (Intel/ARM, 32/64Bit).

GitHub offers hosted virtual machines to run workflows. All virtual machines contain an environment of tools, packages, and settings available for GitHub Actions workflows to use.

So our workflows can simply use these environments. The workflows consist of several steps, each of which can be executed on a different runner. Remember that I’ve written: “You can build a Xojo plugin without your own machine involved”?

In the following ScreenShot we’re seeing that the Linux-ARM64 plugin part is being created on a Ubuntu 24.04.1 ARM machine.

macOS

• Runs on a GitHub macOS virtual machine.
• Uses the preinstalled Xcode command line tools to build “Intel x86_64” and “ARM64” and combine the two to a universal binary.
• CodeSigns with credentials added as repository secrets.

Linux

• ARM32, ARM64
  • Runs on a GitHub Linux virtual ARM machine.
  • To always have exactly the same build toolset (e.g. so that it doesn’t matter if GitHub updates to a newer Ubuntu version) it leverages a Docker container (e.g. arm64v8/gcc) – and actually builds the source inside the Docker container.
• i386, x86_64
  • Runs on a GitHub Linux virtual Intel machine.
  • Also uses a gcc Docker Image to build the source.

Windows

• Runs on a GitHub Windows virtual machine.
• Uses the preinstalled Visual Studio environment to build all “win32”, “x64” and “ARM64”.

How to Build your Xojo Plugin

I’m very well aware that this article can’t help you build your plugin. Each one is individual and needs its own steps and processes.

However, should you consider automating your plugin build process. You might want to look in more detail in the open-source plugin source and the workflows which are building CubeSQLPlugin for all required targets and architectures.

How to Transition from Manual to Automated

While creating a plugin, one doesn’t think of its build process in the early stages, maybe not even for the first few released versions. 

Plugin building is usually a manual process, requiring manual execution of a lot of steps and commands on various machines. It is tedious and prone to errors. It takes time, which adds up the more you build. There’s a point when one should think about streamlining and automate the process, allowing for building new versions without too much effort.
In addition, it’s certainly a good idea to have a consistent build environment other than your own development machine as you could install and change things on there which could impact the builds. That’s why building inside a Docker container is an interesting approach – it will remain exactly the same each and every time, even if the host machine is changed (e.g. by being updated to a new operating system version).

All that used to be like that before having written the GitHub workflow.

How can you transition from a manual to an automated process for your own project? I won’t be able to provide all answers. But, I’d like to give a few ideas of possible steps, with no intention of them being complete or the best choice for your project.

• Use a version control system.
  • Git and GitHub are (for many use cases) free.
  • Using a Cloud solution serves as a backup should something happen to your machines.
  • You can additionally benefit from other services such as the GitHub Actions workflows mentioned in this article.
• Everything that is only in your head should go into some written form. Once you don’t need to do something for some time, you might forget or miss something.
  • Start with documenting all steps, commands, and actions.
• Try to get rid of manual steps. Are you copy-and-pasting several commands to a terminal each and every time?
  • Put them in a shell script, so that you only need to run one command.
  • You can use these scripts later when going to a fully-automated system.
• When initial development is finished and you’re ready to release:
  • Don’t do releases from your development machine. It might be defunct, broken, stolen, or you’re installing some new cool stuff and suddenly notice issues with other projects. Having a dedicated build machine is one idea.
  • Another is going the “GitHub Actions” way which also has its benefits.
    • Runners are virtual machines that are provisioned and “fresh” every time. It’s always the very same environment to start with for each build, no matter what you’re doing during a build.
    • You don’t need to maintain many different build machines yourself. This can even solve some security issues, as it’s probably not your main interest of keeping everything up to date. I prefer to focus on programming and not on system maintenance.
    • However, the runners might be outdated in a few years – and new runners (with newer operating systems) will be available.
      • That’s usually not a very big issue on macOS and Windows since their build tools are usually backwards compatible for quite a long time.
      • Especially for Linux we have decided not to rely on the provided host but use a Docker Image and run the builds inside a Docker container. So you can, for example, use a Docker container with an image that perfectly fits your lowest compatibility needs, while the host itself might only have (too) new libraries installed.
  • Start putting all your steps and scripts into a workflow – be it just on your dedicated build environment, or using GitHub Actions.
    • Certainly separate them per required host (macOS / Windows / Linux).
    • Split a long script into smaller parts, e.g: Download LibreSSL, Build x86_64, Build arm64, Build Universal.
      • In case of an error, it’s easier to see that “macOS: Build arm64 has failed”, compared to “Build for macOS has failed” (because it’s all in a lengthy script).
• Running the workflows manually is great and likely more than good enough.
  Once the project activity grows (e.g. you’re receiving a lot of pull request or have many developers working on it):
  • Ensure that the build and test workflows are running on each pull request, require them to complete successfully before being able to merge. That by the way has been explained in the previous blog post Xojo GitHub Actions. After all, no one wants to find out after many commits that the build is no longer working, and then have to search the history for what might have caused the problem.
• You’ll notice that once it’s all automated you no longer miss it. It causes no additional effort for you, instead bringing a lot of benefits (such as noticing early when code changes cause oddities in tests and builds).

A Fun Fact

In the early days a build of the CubeSQLPlugin often took a couple of hours – and with personal attention needed so that one couldn’t work on much else during that time.

The first iteration of the workflows reduced the entire build (LibreSSL + Plugin) to about 25 minutes. With no attention and manual interaction needed – which means more time for other work. What took the longest was the LibreSSL ARM builds – they have been run on Intel hardware with QEMU for ARM emulation.

Back to the beginning of this article and Xojo’s 2025 Year of Code initiative – in February I have improved the workflows to use the newly available GitHub Actions runners that run on ARM hardware. Which means that no more emulation is required – and the build time has now come down to about 4 minutes for LibreSSL Libs (required only once per new LibreSSL version) and 2.5 minutes for the Xojo database plugin for all its supported platforms and architectures!

That’s All Folks!

I hope this brief introduction of how to use GitHub Actions workflows and Docker to build a Xojo plugin has been helpful to some, food for thought to others.

Jürg Otter is a long term user of Xojo and working for CM Informatik AG. Their Application CMI LehrerOffice is a Xojo Design Award Winner 2018. In his leisure time Jürg provides some bits and pieces for Xojo Developers.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

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

Layout Editor

The Layout Editor has been enhanced with two settings that can adjust the layout.

The command bar has two toggle buttons. The first one already existed and it is for displaying the layout in portrait (the default) or landscape.

The new toggle button displays the layout in a phone size (the default) or a tablet size. When you switch between any of these toggles, the locking is applied to the controls on the layout.

The layout editor also remembers the selections so that the next time you visit the layout, it will be where you left it. Here you can see a landscape tablet layout:

Default Screen

The App Inspector has an additional Default Tablet Screen property. When your app is launched on a phone or tablet-sized device, the specified screen is what gets displayed.

You can also choose “None” for a default screen if you just want to share a single screen across both types of devices.

If you choose “None” for the Default Phone Screen, then the app won’t launch on a phone. If you choose “None” for a Default Tablet Screen, the app will launch on the tablet using the Default Phone Screen, which matches prior behavior.

Design Considerations

Xojo for Android uses locking to automatically adjust controls on the layout. Locking will work for certain types of layouts that you want to run on both phones and tablets, but may not be sufficient for more complex layouts. In these situations, you are better served by designing completely separate layouts for phone and tablet and then using the above Default Screen properties to show the correct one.

When you need to show additional screens, you can show the phone or tablet screen in code by checking the device using DeviceData.Orientation and DeviceData.UserInterfaceType.

If System.Device.UserInterfaceType = SystemDeviceData.UserInterfaceTypes.Tablet Then
  // Show tablet screen
  myTabletScreen.Show
Else
  // Show phone screen
  myPhoneScreen.Show
End If

When you have multiple screens, it often makes sense to put the UI in containers and then use the containers on the different screens.

You can run your apps on a Tablet emulator for testing (you can create one using Android Studio) or you can debug directly on device. I enabled on-device debugging for a Lenovo Tab M10 Plus 3rd Gen with these steps:

• Go to Settings.
• Select About tablet.
• Tap 7 times in a row on the build number. This enabled Developer options. You may be prompted to enter your PIN.
• Select System and then Developer Options.
• Turn on USB debugging and give it permission.

The tablet will now appear as a debug device in Xojo, allowing you to run your Android projects on it.

What about Chromebook?

Some Chromebooks are able to run Android apps and those that can are also able to run Xojo’s Android apps. Android apps can be installed via the Play Store (give CatsUp a try) or manually, although doing it manually is rather difficult (I have not yet gotten that working on my Chromebook). The Play Store options works well, however. Here’s CatsUp from the Play Store running on my Lenovo 300e Chromebook:

When run on the Chromebook, Android apps can have a size of Phone, Tablet or Resizable. You can see that as an option in the title bar of the above screenshot. For best results you probably want to design your apps for a landscape tablet.

Xojo for Android does not have direct support for Chromebook features at this time, but if there is something you’d like to see, be sure to create an Issue so that we can look into it.

Since Chromebooks are just (low-end) Linux machines at their core, they can technically run Xojo Linux apps (x86 or ARM depending on the Chromebook), but this usually requires some sort of additional Linux installation.

And of course, Chromebooks are typically meant to run web apps, which Xojo can also do quite well.

Eddie’s Electronics Example Project

The Android Eddie’s Electronics example project has been updated to run on both phones and tablets. It makes use of Containers to contain the UI and displays them using screens for the appropriate device type.

Here you can see the Customer screen for a tablet displays the list of customers on the left, with details and invoices on the right.

Compare that to the phone version which has you navigate between that information using separate screens.

Tablet supports opens up a whole other category of users for your Android apps and should be particularly useful to those making bespoke apps for clients.

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

Enhanced Emoji Rendering

While Xojo’s Graphics class supported rendering emojis on Windows and Linux, their appearance was less appealing.

Now in Xojo 2024r2, we’ve enhanced emojis with vivid colors!

You’ll notice that other parts of the Xojo framework that utilize the Graphics class, such as the ListBox, have also benefited from this update.

Understanding Emojis at a Deeper Level

Understanding how emojis are encoded is crucial for grasping how Xojo’s String type works and how we interpret them. Any text or emoji displayed on the screen can be considered a Unicode sequence or a series of Unicode sequences. At a deeper level, a single Unicode sequence can be constructed from multiple Unicode code points (i.e., bytes of data). For clarity, we’ll describe one character (whether simple text or an emoji) as being composed of Unicode sequence(s).

To demonstrate, let’s try to understand the woman

This particular woman is not very complex, it is made up of one single Unicode sequence (with corresponding code points). Our String type can easily handle this one Unicode sequence and reports correctly that the Length of the String is 1 (even though the entire emoji is made up of 4 bytes of code points).

Now let’s take a look at a more complicated woman

The only difference visually is that this woman has fiery red hair. This subtle change in appearance means that to construct this emoji requires not 1, not 2, but 3 distinct Unicode sequences (with a grand total of 11 bytes of code points).

Note that the reported length of the String is 3 Unicode sequences, even though we visually see only one character. This distinction is very important in understanding how String functions work. Xojo’s String functions inherently deal with Unicode sequences, not individual characters. When you do need to work with complex emojis like these, you will want to utilize our String.Characters API which effectively manages this complexity.

An Optimized String.Characters

Given the prevalence of emojis in everyday text and messages, properly handling them within Xojo’s String type is crucial. While we initially introduced this feature as String.Characters, it functioned as an iterator until Xojo 2024r2. Now, String.Characters returns a String array, which can still be iterated, ensuring existing code continues to work as before. Additionally, this update offers the added advantage of significantly improved speed, especially on Windows and Linux. Along with this update, we introduced String.CharacterCount, which is useful when you need to know the number of characters in a string without storing them all in an array.

To further understand emojis and their corresponding Unicode sequences, check out this Full Emoji List.

William Yu grew up in Canada learning to program BASIC on a Vic-20. He is Xojo’s resident Windows and Linux engineer, among his many other skills. Some may say he has joined the dark side here in the USA, but he will always be a Canadian at heart.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

And what do we mean by the transitory character of Popover windows? Well, and here comes one of the first differences from Modal windows. When a Popover is visible and the user clicks or taps on any other element of the graphical interface not contained in the Popover itself it will close, hence transitory. So, you don’t have to include the typical “Close window” button in a Popover (though you can), since it will close when the user clicks outside of it, i.e. when the Popover loses focus.

Where are the Popover Window Contents?

Where do you define the content displayed in a Popover window? While in your Web app, you can do it on any Container control added to the project. In the case of Desktop and iOS apps, you can do it on either the designs of a Container Control or any Window or Screen added to the project.

For example, here you can see that the content shown as a Popover in the previous screenshot is actually that of a Window (Window2) added to the project:

This introduces additional flexibility allowing your app’s logic to decide when to display a Window or Container instance as you have been doing until now, or display it as a Popover.

Showing a Popover

Displaying a Popover is very straightforward, whether it is created from a Container or a Window, the method is the same:

DesktopContainer.ShowPopover(parentControl As DesktopUIControl, facing As DesktopWindow.DisplaySides = DesktopWindow.DisplaySides.Bottom, detachable As Boolean = True)

The explanation of the expected parameters is as follows:

• ParentControl: The control that will act as the parent, or on which the Popover will be pointing to.
• Facing: The direction in which the Popover will point on the parent control; by default it will appear under the parent control, but you can use any of the values available in the DesktopWindow.DisplaySides enumerator (or the iOS equivalent).
• Detachable: This value only applies to macOS Popovers, since said operating system has the ability for the user to “detach” the Popover from the parent control as long as this value is defined as True. To detach, drag the Popover with the mouse cursor.

Let’s say we have a window called Window2 and a button called MyButton. In the Pressed event of MyButton we can use the following lines of code to display Window2 as a Popover:

Var w As New Window2
w.ShowPopover(me)

And that’s all!

Platform Differences

In the previous section we already pointed out the first: macOS is the only operating system that acts on the value indicated in the Detachable parameter. But there are some other considerations to keep in mind so you don’t get caught off guard:

• Beyond the limits. Although in Windows and macOS Popovers can exceed the limits of the window on which the parent control is located, the position of the popover in Linux is restricted to the limits of the window that contains the parent control. This is the same for iOS and for Web pages.
• iPhone and iPad. When a Popover is displayed on an iPhone, it will look like a modal window; while if the same application is run on an iPad, the appearance will be the typical one expected from Popovers: the window pointing to the parent control in the indicated direction.
• On the Web. The contents of a Popover are those defined in a Container control, while on the rest of the platforms you can use both Container controls and Windows / Screens.

Why the Popover doesn’t “point” in the configured direction?

By default it will try to do so according to the value that has been set in the “facing” parameter, but if it does not find enough space on the margins of the screen, then it will be displayed on the next side of the parent control in which there is available space for display the Popover in its full width and height; This is true on macOS, Linux, Web and iOS.

Can I reuse a Popover?

No, You can not. Whether you use a Container control or a window as the source of the UI design to be displayed by the Popover, do not lose sight of the fact that the Popover is just another type of window; and therefore behaves as such. That is, once it is closed either because it has lost focus or because you have closed it explicitly through code invoking the Close method, all the displayed controls and the rest of the internal structures will be closed / invalidated, so that although the instance If a Popover is not Nil (because, for example, you keep a reference to the window or container instance used as the UI source), you will not be able to invoke the ShowPopover method again on said instance but you will have to create a new instance of the Container/ Window used as the source of the UI to be displayed by the Popover.

How can I communicate with the UI elements contained in the Popover?

You would do so just as you would do with any other type of window that you have been using so far in your Xojo projects.

Conclusion

Without a doubt, Popovers are a new way to improve the design of your apps’ user interfaces, providing a more direct relationship between the user interface elements displayed in the Popover and the “parent” control in charge of displaying it. Furthermore, since you can use any window or container you want as the source of the UI to be displayed by the Popover, you will have greater flexibility about when you want to display them in a Popover or display them using any other of the available window types or, in the case of Containers, embedding them as part of other UI elements at runtime.

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

Xojo Linux is Free

We have made building for Linux free and included in the Xojo IDE! This means that on Linux you get a version control ready IDE, along with the ability to build desktop and console Linux apps (including Raspberry Pi), all for free. Launch Xojo 2024r1 (or any later release of Xojo) and open any desktop or console project, go to Build Settings, select Linux and in the Inspector choose the appropriate Architecture that matches the Linux OS you want your app to work on, either ARM or x86. Click Build to compile your project to a standalone app that you can then run on Linux – no license required.

Wrapping Up

All these changes were made based on feedback from the Xojo community and to better match the changing ways that people develop and share software projects. With this change Xojo continues its dedication to supporting Linux.

Download Xojo to get started.

Edited 07/2025 to reflect changes to licensing.

Faster HandleURL Responses

With Xojo Web you can create APIs backing your Mobile or Desktop applications. Just by updating to Xojo 2023r4, your web services will get the benefit of much faster responses and the ability to handle many more requests per second.

Just to compare between different Xojo versions, we’ve created some benchmarks using Xojo Web 1 (with Xojo 2019r3.2) and some Xojo Web 2 releases, 2023r3.1 and the latest one, 2023r4.

Here are the results, returning plain text:

And the same test, but this time returning a string generated by JSONItem:

Xojo 2023r4 is capable of serving around 20x more requests per second compared to Web 1, and around 4x compared to Xojo 2023r3.1. And thanks to the reduced latency time, your API will return the contents much faster.

Faster Transfer Rates in Windows and Linux

While working on performance, we’ve found that applications deployed on Windows and Linux were serving large files much slower than those deployed on macOS servers.

William improved the low level code for sockets on those targets, allowing the server to transfer large files at a much faster speed. During my tests, I’ve seen 10x faster transfer rates.

But this doesn’t affect only our Web target! If you are using a ServerSocket with TCPSocket classes, your Console and Desktop applications will also benefit from these improved transfer rates.

Static Assets Cache Control

In this release, we’ve also improved how the framework interacts with the browser. When your user visits your web application for the first time, it will store all of the required JavaScript and CSS files.

This was already happening in previous releases but with a subtle difference. From now on, the browser won’t even need to check with the server if the file has changed since the last visit. This translates to faster load times for your users and less server load for you since the server won’t need to handle all those requests anymore.

Improved Compile Time

In this release, Xojo Web will compile your projects a few seconds faster. The first time you compile your project, it will cache the result of some processes that are only changing between Xojo releases.

Here is a comparison between 2023r3.1 and 2023r4, both are running a debug session of a blank project:

That’s around 3-4 seconds faster every time a project compiles.

Events Improvements

Some web controls were sending information from the browser to the server more frequently than needed. For example, a WebContainer.Scrolled event was being sent for every scrolled pixel, causing unnecessary server load.

We’ve been reviewing these controls and have made some improvements:

• WebCombobox
• WebContainer
• WebSearchField
• WebTextArea
• WebTextField
• WebUploader

All of them will continue communicating their state updates, but the framework will focus on delivering the latest value available.

For example, in a WebSearchField, if the user writes “hello”, the framework will send the first key press (“h”) as soon as it happens. The next event it will send will depend on how fast the user types, so it can be either “hel” or maybe directly “hello”. What is guaranteed is the TextChanged event will be fired for the final value (“hello” in this example).

New Experimental Option

WebSession has a new experimental option available, disabled by default. “Send Events in Batches”:

Turning it on will make our JavaScript framework group different event notifications in a single request. Projects that contain complex layouts that show and hide several controls at once may benefit from snappier GUIs.

As a side effect, it will also ensure the events arrive to the server in the correct order. Think about a login screen where the user has an email field, a password and a “Login” button with the Default setting turned on (to allow the user to trigger the Pressed event by pressing the Enter key). When sending the events in different requests, because of network latencies, the WebButton.Pressed event could arrive at the server before the last WebTextField.TextChanged.

We would love to hear your experiences when turning on this experimental option. If you find an issue, please report it.

Wrapping Up

As always, while Xojo 2023r4 comes with a lot of performance improvements, it also comes with bug fixes and feature requests. I want to again thank everyone who took the time to create new Bug reports and Feature Requests, and tested the pre-releases.

We’re looking forward to see what you build with it!

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Xojo Cloud is optimized for Xojo applications. It is specifically designed to provide the best possible performance and stability for Xojo web applications. We optimize Xojo Cloud for performance, so your web apps will run smoothly and seamlessly. You can even monitor server stats from within the Xojo IDE.

Xojo Cloud is focused on simplicity and ease of use and requires zero configuration. Designed with the Xojo developer in mind, Xojo Cloud’s Control Panel makes it easy to deploy and manage web applications. Purchase a server, open a web project in Xojo and click Deploy to upload and install to Xojo Cloud. Not just for web apps, Xojo Cloud includes Apple Push Notification server (APNs) support for your iOS apps. Set up SSL, PostrgeSQL, MySQL, SFTP and a SSH Tunnel with a click in the Xojo Cloud Control Panel (the Control Panel itself is a Xojo web app). The administration of a web server is a significant and constant task; Xojo Cloud allows you to leave that behind and focus on your projects.

We take security very seriously. Xojo Cloud offers advanced security features to protect your data from cyberthreats, including a smart firewall, intrusion and hacking detection and Security-Enhanced Linux. Unlike most hosting solutions that provide little to no security, each Xojo Cloud server is built with our state-of-the-art, industrial-strength, multi-tiered security system woven into its very core. 

Additional features and benefits include daily automatic backups, load balancing and support from the Xojo team. With nine global hosting locations, you are able to host your Xojo web applications close to your users, for speed and an ideal overall experience.

In addition to the standard options, Xojo Cloud servers with more RAM, storage and Virtual CPUs are available. Contact customer support for details about personalized plans. 

Whether you are a seasoned Xojo developer or just getting started, Xojo Cloud provides an intuitive and user-friendly hosting solution for Xojo web applications. Today is a good day to start using Xojo Cloud, visit our website to learn more or see the Xojo Store to pick your package and location.

• 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

This technique is strongly based in the NiceLabels algorithm that can be found in StackOverflow ported to several programming languages, so… why not to Xojo too? In fact, it was a piece of cake porting it from JavaScript to Xojo due to the similarities of both languages,

Of course, if you just want to jump into the class itself, you can download the project from this link.

Let’s start creating the class itself. I’ve named it NiceScale with all the required properties. To begin, add a new Class to a Xojo project. Then, with the class selected in the Navigator, add the following properties:

• MaxPoint As Double, setting the Scope to Protected
• MinPoint As Double, setting the Scope to Protected
• Spacing As Double, setting the Scope to Public
• NiceMaximum As Double, setting the Scope to Public
• NiceMinimum As Double

Next, add the methods starting with the Constructor.

• Method Name: Constructor
• Parameters: min As Double, max As Double
• Scope: Public

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

If Min = Max Then Max = Min + 1

Self.MinPoint = Min(Min, Max)
Self.MaxPoint = Max(Max, Min)
Self.Calculate

As you can see here, the Constructor calls the Calculate method; so let’s add that one:

• Method Name: Calculate
• Scope: Protected

And type this code in the associated Code Editor:

Var range As Double

range = niceNum(MaxPoint - MinPoint, False)

Spacing = niceNum(range / 9, True)

NiceMinimum = Floor(MinPoint / Spacing) * Spacing
NiceMaximum = Ceiling(MaxPoint / Spacing) * Spacing

Once again, this method is calling the NiceNum method, so let’s add that one to the
NiceScale class:

• Method Name: NiceNum
• Parameters: range As Double, round As Boolean
• Return Type: Double
• Scope: Protected

And type the following snippet in the associated Code Editor:

Var exponent As Double
Var fraction As Double
Var niceFraction As Double

exponent = Floor(Log(range) / Log(10))
fraction = range / Pow(10, exponent)

If (round) Then
  If (fraction < 1.5) Then
    niceFraction = 1
  ElseIf (fraction < 3) Then
    niceFraction = 2
  ElseIf (fraction < 7) Then
    niceFraction = 5
  Else
    niceFraction = 10
  End If
Else
  If (fraction <= 1) Then
    niceFraction = 1
  ElseIf (fraction <= 2) Then
    niceFraction = 2
  ElseIf (fraction <= 5) Then
    niceFraction = 5
  Else
    niceFraction = 10
  End If
End If

Return niceFraction * Pow(10, exponent)

Lastly, let’s add a couple of useful methods for the class: GetValues and SetMinMaxPoints. The first one will let us get the Array of the already equally spaced Double values, while the second one will let us set a new pair of minimum and maximum values without needing to create a new instance of the class:

• Method Name: GetValues
• Return Type: Double()
• Scope: Public

Typing the following snippet in the associated Code Editor:

Var values() As Double

For n As Double = Self._NiceMinimum To Self._NiceMaximum Step Self._mSpacing
  values.add n
Next

If values(0) > 0 Then
  While values(0) <> 0
    values.AddAt(0, values(0) - Self._mSpacing)
  Wend
End If

Return values

• Method Name: SetMinMaxPoints
• Parameters: min As Double, max As Double
• Scope: Public

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

If Min = Max Then Max = Min + 1

MinPoint = Min(Min, Max)
MaxPoint = Max(Max, Min)
Calculate

NiceScale in Practice

Let’s create the UI for a Desktop project so we can put our NiceScale class in practice; and because we are going to need some custom drawing, drag a Canvas from the Library to the project Navigator. That will create a canvas subclass. With the just added Canvas subclass selected in the Navigator use the associated Inspector Panel to set the following values:

• Name: ScaleDrawing

Then, add the following property to it:

• Name: range
• Type: NiceScale
• Scope: Private

Add a new Method to our ScaleDrawing subclass using the following values:

• Method Name: Constructor

And typing these lines of code in the associated Code Editor:

Super.Constructor
Self.range = New NiceScale(0, 1)

Then, add a second method using the following values:

• Method Name: Redraw
• Parameters: minValue As Double, maxValue As Double

And typing these two lines of code in the associated Code Editor:

range.SetMinMaxPoints(minValue, maxValue)

Self.Refresh

After that, let’s do the drawing itself! So we need to add the Paint event to our ScaleDrawing class. When done, add the following lines of code to the associated Code Editor:

g.DrawRectangle(0, 0, g.Width, g.Height)

Var values() As Double = range.GetValues
Var offset As Double = (( g.Width ) / values.LastIndex) - 10
Var x As Double = 20
Var y As Double = g.Height / 2 - 5
Var tx As Double
Var Val As Double

For n As Integer = 0 To values.LastIndex
  Val = values(n)

  g.DrawLine( x, y, x, y + 10 )

  tx = x - g.TextWidth(values(n).ToString) / 2

  g.DrawText(values(n).ToString, tx, y + 10 + g.FontAscent)

  x = x + offset
Next

g.DrawLine(20, y, x - offset, y)

Creating the NiceScale Example UI

Select the Window1 window in the Navigator so it is displayed in the Layout Editor. Next drag the ScaleDrawing class from the Navigator and drop it into the Layout Editor so it looks like like this (locking the four locks for ScaleDrawing1 in the Inspector Panel):

Next, add a couple of Labels, two TextFields and a Button below ScaleDrawing1 in the Layout Editor so our final UI looks like this:

Rename Label1 as MinimumLabel, Label2 as MaximumLabel, TextField1 as MinimumTF, TextField2 as MaximumTF, and Button1 as DrawBT. Then, add the Pressed event to DrawBT and type the following code in the associated Code Editor:

ScaleDrawing1.Redraw(MinimumTF.Text.ToDouble, maximumtf.Text.ToDouble)

That’s all!

Running the app!

Everything is in place, so run the app and put some values in the Minimum and Maximum textfields, clicking the button to refresh the drawing. These are some examples you will get for the following range values:

• By Default:

• Minimum: 12, Maximum: 112

• Minimum: -345, Maximum: 835

• Minimum: -816, Maximum: 25

As you can see, having these classes in your developer bag is a good thing if you need to draw this kind of scale! Use the ScaleDrawing class as a start point for your own needs.

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

Opening in Desktop and Mobile Apps

• First, the App Opening event will be fired first.
• Next, the Opening event on every control of the default Window assigned to the App project. In this case, it will follow the same order in which the controls were added to the Window in the Layout Editor. It is possible to change that order using the Order buttons in the Command Bar in the Layout Editor.
• Last, the Opening event will be fired on the default Window containing the controls.

Closing in Desktop Apps

When a Window is closed in a Desktop app, the Closing event will be fired following this order:

• First, the Closing event will be raised on every control added to the Window, following the same order used when adding the controls to the Window in the Layout Editor. It is possible to change that order using the Order buttons in the Layout Editor toolbar.
• Next, the Closing event will be raised in the Window itself.
• Last, the Closing event will be raised in the App object of the Desktop app when the user quits the application.

Opening in Web Apps

This is the event firing order for Xojo Web apps:

• First, the Opening event will be raised in the WebApp object.
• Next, the Opening event in the WebSession object.
• Next, the Opening event on every control added to the by default WebPage set in the WebApp object. In this case, it will follow the same order used when adding the controls to the web page in the Layout Editor. (It is possible to change that order using the Order buttons in the Layout Editor toolbar.)
• Next, the Opening event will be raised on the default web page itself.
• Next, the app will start to raise the Shown event on every one of the webpage controls following the same order used when they have been added to the page. (It is possible to change that order using the Order buttons in the Layout Editor toolbar.)
• Last, the Shown event will be raised in the default webpage.

Closing in Web Apps

Regarding the Closing and Closed events, the Web App will follow this order:

• First, the Closing event will be raised in the WebSession object.
• Next, the Closed event will be raised on every one of the default webpages (or the pages shown), following the same order used when adding the controls to the page in the Layout Editor. (It is possible to change that order using the Order buttons in the Layout Editor toolbar.)
• Last, the Closed event will be fired in the webpage itself.

Summary

As you can see, Xojo follows the firing same regardless of the target you choose for your project – Desktop, Web or Mobile apps. Obviously, Web apps do change a bit, because they deal with the WebSession object and also with the Shown event in addition to the Opening event. In Web projects, the Opening event happens on the server side, while the Shown event happens in the client (browser) side.

See related video at the Xojo Programming Language YouTube Channel.

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

Xojo Web is an excellent way to expose the features of your electronics projects without having to attach any screen to them. It’s never been easier to build a Web GUI for your smart clocks, drones, POS, domotics, robots or just some automation services. Thinking about building a solar powered server to automate your tweets? Why not!

If you prefer, you can just expose a Web API instead that can be remotely consumed from another device.

What Raspberry Pi boards support ARM 64-bit Linux OS?

• Raspberry Pi Zero 2
• Raspberry Pi 3
• Raspberry Pi 4
• Raspberry Pi 400

Preparing your Raspberry Pi

The easiest way to get your operating system ready is by using the Raspberry Pi Imager.

At the moment of writing this article, it selects the 32-bit flavor by default. If you have one of the supported boards, go ahead and try Raspberry Pi OS (64-bit) or Raspberry Pi OS Lite (64-bit). The later won’t include any desktop environment, you’ll have to access by SSH.

Select your SD Card storage and press on Write. Optionally, if you want to set a hostname for your board, enable SSH, or even configure your Wifi, press on the gears icon.

In just a few minutes you will have a ready to boot SD card for your Raspberry Pi.

Remotely debugging your projects

This is one of my favorite features of Xojo.

In your Xojo installation Extras folder, you will find a “Remote Debugger Console” and “Remote Debugger Desktop”, that also works for your Linux 64-bit OS.

Depending on which flavor of Linux you’ve selected in the previous step, send the Console or Desktop ZIP to your board, run it and configure the settings.

Inside Xojo, go to Preferences and press on the Debugging tab.

That’s it. Now you will be able to remotely run and debug your applications. Add a few breakpoints and the execution will stop as soon as it reaches it, allowing you to explore the current state.

Deploying the final version

Once you’re ready to build the final version of your application, all the wires attached and components soldered, the last step is to “Deploy” your application.

There is a tutorial covering this step in detail: Deploying Web Apps on Linux.

If you create a Raspberry Pi project, please make sure you open a Forum thread. The Xojo community loves seeing this kind of projects!

What will you build?

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

Depending on your flavor of Linux (in this example we’re using Gnome on Ubuntu 20.04), you can change themes from your Settings/Appearance sidebar:

And for those interested in other themes, you can also change themes at the command line:

gsettings set org.gnome.desktop.interface gtk-theme 'Yaru-dark'

Xojo will be able to determine which themes are dark mode savvy. Now you are ready to enjoy the dark side of Linux along with Xojo!

William Yu grew up in Canada learning to program BASIC on a Vic-20. He is Xojo’s resident Windows and Linux engineer, among his many other skills. Some may say he has joined the dark side here in the USA, but he will always be a Canadian at heart.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Xojo’s team was all vaxxed-up and so happy to get together in Nashville for #XDC2022. Tennessee’s Music City was a delightful backdrop for the first in-person Xojo event since 2019. Check out the short highlights video from Nashville and then join us for #XDC2023 in London, UK. You can register here.

This year the Xojo team and community welcomed a new Xojo engineer, Ricardo Cruz. Ricardo has applied his expertise to advance and improve Xojo Web. To quote one of Xojo’s engineers, “Ricardo coming in has been awesome,” a sentiment echoed on the Forum and the community in Nashville.

Xojo Web has come so far this year. Control reliability has improved, IDE previews have improved and reconnections have really improved. The web framework can now more often reconnect back to the same web session if it still exists. This is one of the things Ricardo is really happy about, “You can switch to your email app in your mobile, copy something to the clipboard, come back to the web app and it is still there, ready to continue.” Under the hood, some dependencies received updates, like jQuery. As a user, you don’t have to do anything, just use the new Xojo version! Try to tell that to another web developer, that’s sci-fi outside of Xojo. Also, thanks to the community, the memory and CPU usage continues to be improved release after release. “Honestly from my perspective it is just fun to play with little projects in it because it has really matured,” says Xojo’s Director of Engineering, Travis Hill.

Speaking of technical achievements, this year we added two new targets to Xojo: Windows on ARM 64 and Linux on ARM 64. On Windows, you can natively deploy to ARM-based tablets and laptops that run Windows. On Linux, you can deploy to 64-bit Raspberry Pi which can address significantly more RAM than 32-bit versions.

We built the Xojo Cloud Control Panel with an updated version of Xojo, and thanks to some Web framework improvements the controls now stay more responsive under load. Plus we’ve added Xojo Cloud servers in Sydney, Australia for web developers in Australia and New Zealand. We also continued improving and testing our upcoming support for Android, which is now feature complete and awaiting some remaining bug fixes before we make it available to everyone.

In addition, we want to brag about a few technical improvements, including the numerous PDF updates implemented by Xojo Engineer and now PDF expert, Javier Menéndez. Also there is the option to generate Program Database (PDB) files on Windows and improved multi-monitor support shepherded by Xojo Engineer William Yu. The list goes on: Code Assistants, on-device debugging in iOS, new Xojo Documentation site, adding Controls at runtime, loading speed faster for big projects, and the time team-Lefebvre built a web app to Calculate Combat Rolls in Twilight Imperium…

Inside Xojo we improved a lot too. Besides welcoming Ricardo and his beard to the team, we migrated Xojo’s bug and feature reporting platform from the internally managed Feedback tool to the much loved Issues. This has increased productivity, streamlined work flow, made it easier to search and find, comment, edit. The team couldn’t be happier!

This year also included Xojo’s first Bug Bash in a long time! During the Bug Bash, Xojo’s Code Editor got some much needed improvements resulting in noticeably faster updates. Plus updates to the Syntax Help Area thanks to Xojo Engineer and retro-computing expert, Paul Lefebvre. Besides the very real smashing of 100 bugs, the bash had the unintended consequence of giving the engineers an opportunity to work on things they don’t normally work on, giving engineers opportunities to collaborate and better solve things.

All in all, 2022 was a year of forward movement for Xojo. Which has us leaning into 2023 with a lot of excitement and expectation. Our team is committed to continuing to make Xojo the best cross-platform development tool and we thank you for being part of Xojo’s continued success!

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

Emojis are available on every operating system and platform that Xojo supports from desktop to mobile to web. Because they are built-in to the OS as characters, they are client-side which means that web applications don’t have to load them from the server as they are already available to the browser from the user’s OS. As characters, they are scalable to any font size. There are also a lot of them. According to Emojipedia (yes, that’s a thing), there are over 3,600 emojis as of September 2021.

Emojis can be especially useful for listboxes in web applications because unlike the DesktopListBox, the WebListBox does not have a PaintCellBackground event that can be used to draw graphics into a cell. Instead, if you can find an emoji that represents what you’d otherwise draw into a cell, you can simply assign it without having to deal with graphics at all. For example, there are a series of emojis that are just boxes in different colors that could be used to indicate the state of something: . The famous web game Wordle uses these when you share your results. With over 3600 available, you can likely find an emoji to represent nearly anything you might need from the common smiling face to the less common umbrella on the ground , banjo or moai from Easter Island.

Again, emojis can be used in any type of application, desktop, mobile or web. Here’s an example of them in a web popup menu:

And here they are in a web list box:

The key thing is to realize that they are individual characters which means they can appear alone or mixed in with other characters. If you need them to be larger, increase the font size. Here’s the lion for example at 60 point size:

Because they are characters, you can copy and paste emojis anywhere you’d use a character, including in your code:

ListBox1.AddRow("Fox 🦊")
ListBox1.AddRow("Lion 🦁")
ListBox1.AddRow("Chipmunk 🐿")

Just remember that emojis are characters, not graphics, so you should treat them as such. Notice in the code above, they are inside the quotes. You could even use them to name a variable:

Var 🌋🥥💰 As String = "Yes, you can do this!"

I’m not sure that’s useful, but it clearly demonstrates how an emoji is a characters like any other.

On Emojipedia you can search for emojis by keyword and copy them to the clipboard. Again because they are simply characters, you can then paste them into a Xojo constant, make them the default value of a property or even paste them into the Code Editor to assign them in code.

Keep emojis in mind the next time you need an image in an application.

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

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