What this project includes

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

Download

You can download the entire Xojo project from GitHub.

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

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

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Year of Code Project

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

How to Play:

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

The Prizes:

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

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

For the most part, writing drawing code will just work because you use Xojo’s Graphics class for Android, Desktop and iOS projects. Web projects, however, don’t use the Graphics class. The WebCanvas control’s Paint event is passed a WebGraphics object. While the Graphics and WebGraphics classes have a lot in common, sharing many of the same methods with the same parameters, they are two distinctly different classes from the perspective of the Xojo compiler. That means that while the code you write will look almost identical, you still have to use a Graphics object for Android, Desktop and iOS projects and a WebGraphics object for Web projects.

Your instinct might be to simply write the code for one and then copy it to the other projects, changing Graphics to WebGraphics for Web projects. This will of course work, but then you have to remember to do this copy/paste/change operation every time you update your code. That’s not ideal.

Graphics vs. WebGraphics

With Xojo, the code can be written in such a way as to automatically handle the difference between Graphics/WebGraphics. Most often your graphics methods will be called from something that provides a Graphics or WebGraphics object for you to draw into such as a Canvas control’s Paint event. From there your code will call your methods that do the drawing. The problem is that your methods can’t use a Graphics or a WebGraphics type as a parameter because Graphics is not going to work for your Web projects and WebGraphics doesn’t exist in any framework except the Web framework. Thus using it anywhere else will result in a compiler error.

Using a Variant

Getting around this limitation is, fortunately, quite easy. Instead of using Graphics or WebGraphics as a parameter type, you use Variant. A Variant can hold any type of data from Strings to Integers, to Graphics to WebGraphics and more.

Once your drawing method gets the Variant though, it can’t use it to draw. It can only use a Graphics or WebGraphics objects. The trick is to then copy it into a Graphics or WebGraphics class variable:

Var g As Graphics = context

or

Var g As WebGraphics = context

The problem you now face, as mentioned earlier, is that WebGraphics only exists in Web projects. That means you have to write your code in such a way that you will declare the variable g as a Graphics object in Android, Desktop and iOS projects and as a WebGraphics object in Web projects. This can be achieved via conditional compilation. This is a simple technique that tells the Xojo compiler to only compile code into your app if conditions you specify are met. In this case, if you’re targeting Desktop or Mobile, it should compile in the line that uses the Graphics type, and if you are targeting a Web app, the line that uses WebGraphics. To conditionally compile, you just need to add that conditional code around these two lines:

#If TargetDesktop Or TargetMobile Then
   Var g As Graphics = context
#EndIf

#If TargetWeb Then
   Var g As WebGraphics = context
#EndIf

Since a project must be only one of the above types, when you run or build your project, the appropriate line of code will be compiled in. From there, you now have a variable (g) of the right type can use this to draw whatever you like. For example, there are four identical example projects (one for each project type) that show off this technique. They can be found in the Xojo IDE by choosing File > New Project, clicking on Examples, choosing the Graphics folder in the list and then the Cross-Platform Drawing folder. The examples all draw a checkerboard that looks like this:

They all contain the an identical Checkerboard class that handles the drawing. This class has DrawBorder and DrawCheckers methods that both take a Variant as a parameter. In each project is a Canvas control whose Paint event calls these methods:

Var cb As New Checkerboard
cb.DrawBoard(g)
cb.DrawCheckers(g)

The full DrawBoard method looks like this:

#If TargetDesktop Or TargetMobile Then
  Var g As Graphics = context
#EndIf

#If TargetWeb Then
  Var g As WebGraphics = context
#EndIf 

Var boxSize As Integer = Min(g.Width/8, g.Height/8) 'The size of the box
'Draw the rows
For y As Integer = 0 To 7
  For x As Integer = 0 To 7
    'Switch colors for each box in the row
    If g.DrawingColor = Color.Black Then
      g.DrawingColor = Color.White
    Else
      g.DrawingColor = Color.Black
    End If
    'Draw a box
    g.FillRectangle(x * boxSize, y * boxSize, boxSize, boxSize)
  Next
  'Switch colors again for the beginning of the next row
  If g.DrawingColor = Color.Black Then
    g.DrawingColor = Color.White
  Else
    g.DrawingColor = Color.Black
  End If
Next

In the example projects, check out the DrawCheckers method as well. It uses the same technique. What is great about this is that this class can be copied into any Android, Desktop, iOS or Web project and it will indeed just work.

Checking Out the Examples

There are four example projects (one for each project type – Android, Desktop, iOS and Web) that demonstrate the technique explained here. You can find them in the Xojo IDE by choosing File > New Project, clicking on Examples, choosing the Graphics folder in the list and then the Cross-Platform Drawing folder.

Geoff Perlman is the Founder and CEO of Xojo. When he’s not leading the Xojo team he can be found playing drums in Austin, Texas and spending time with his family.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

In this blog post, we’re going to unlock the power of Xojo’s DesktopCanvas and its Graphics capabilities to recreate one of the popular SpinKit loading animations originally created by Tobias Ahlin. We’ll be implementing the “Three Bounce” animation, transforming this beloved CSS animation into native Xojo code!

Not only will you learn how to create this specific animation, but you’ll also gain valuable insights into animation principles in Xojo that you can use to create your own custom animations. By the end of this tutorial, you’ll understand how to:

• Harness the power of DesktopCanvas for custom graphics
• Create smooth animations using Timers
• Implement phase-based animations
• Use Graphics methods to draw dynamic shapes
• Manage animation lifecycles properly

Why This Matters

Loading animations are more than just eye candy – they’re essential UI elements that keep users engaged while your app processes data. Instead of using static images or third-party libraries, creating your own animations gives you complete control over the look and feel of your application while keeping your dependencies minimal.

What We’re Building

We’ll create a smooth, professional-looking three-dot loading animation where dots gracefully scale up and down in sequence. The result is a lightweight, customizable loading indicator that you can drop into any Xojo project. Here’s what makes this implementation special:

• Pure Xojo code – no external dependencies
• Smooth, fluid animation
• Easily customizable colors and timing
• Efficient resource usage
• Clean, object-oriented design

Ok, let’s start building our awesome animation class.

Step 1: Setting Up the Base Class

First, create a new class (Insert > Class) that inherits from DesktopCanvas:

Protected Class SpinKitClass Inherits DesktopCanvas

Step 2: Defining Core Properties

Add these essential properties to control the animation:

Private animationPhases() As Double      // Stores phase offsets for each dot
Private animationSpeed As Integer = 60   // Animation refresh rate in milliseconds
Private animationTimer As Timer         // Timer to drive the animation
Private currentPhase As Double = 0.0    // Current animation phase
Private dotSize As Integer = 20         // Size of each dot
Private dotSpacing As Integer = 20      // Space between dots

Step 3: Setting Up Constants

Define the constants that control the animation behavior:

Private Const kDefaultColor As Color = &c333333    // Dot color
Private Const kPhaseIncrement As Double = 0.05    // Animation speed

Step 4: Implementing Animation Control Methods

Add methods to start and stop the animation:

Public Sub StartAnimation()
  /// Initializes and starts the animation
  /// Sets up initial phase offsets for the dots
  /// Creates and configures the animation timer
  
  If animationTimer = Nil Then
    animationPhases = Array(0.0, 0.16, 0.32)
    
    animationTimer = New Timer
    AddHandler animationTimer.Action, AddressOf UpdateAnimation
    animationTimer.Period = animationSpeed
    animationTimer.RunMode = Timer.RunModes.Multiple
  End If
End Sub

Public Sub StopAnimation()
  /// Stops the running animation
  /// Removes the timer handler and cleans up
  /// Refreshes the canvas to clear the animation
  
  If animationTimer <> Nil Then
    RemoveHandler animationTimer.Action, AddressOf UpdateAnimation
    animationTimer = Nil
    Refresh
  End If
End Sub

Step 5: Creating the Animation Update Logic

Implement the timer callback that drives the animation:

Private Sub updateAnimation(sender As Timer)
  /// Timer callback that updates the animation state
  /// Increments the phase and triggers a redraw
  /// @param sender The Timer that triggered this callback
  
  #Pragma Unused sender
  
  // Increment the current phase (spin08)
  currentPhase = currentPhase + kPhaseIncrement
  // Reset currentPhase if it exceeds 1.0
  If currentPhase > 1.0 Then currentPhase = 0
  
  // Invalidate the canvas to trigger a repaint
  Refresh()
End Sub

Step 6: Implementing the Drawing Logic

Add the core animation rendering code:

Private Sub animation08(g As Graphics)
  /// Renders a single frame of the three-dot loading animation
  /// Draws 3 dots that scale up and down in sequence
  /// @param g The graphics context to draw into
  
  Var centerX As Integer = Me.Width / 2
  Var centerY As Integer = Me.Height / 2
  
  For i As Integer = 0 To 2
    Var phase As Double = currentPhase + animationPhases(i)
    
    // Ensure phase is within 0 to 1
    If phase > 1.0 Then phase = phase - 1.0
    
    Var scale As Double
    If phase < 0.4 Then
      scale = phase / 0.4
    Else
      scale = (1.0 - phase) / 0.6
    End If
    
    Var size As Integer = dotSize * scale
    Var x As Integer = centerX + (i - 1) * dotSpacing - size / 2
    Var y As Integer = centerY - size / 2
    
    g.DrawingColor = kDefaultColor
    g.FillOval(x, y, size, size)
  Next
End Sub

Step 7: Handling the Paint Event

Implement the Paint event to trigger the animation rendering:

Sub Paint(g As Graphics, areas() As Rect) Handles Paint
  /// Paint event handler that renders the animation
  /// Called automatically when the canvas needs to be redrawn
  /// If animation is running, calls animation08, otherwise clears the canvas
  
  If animationTimer <> Nil Then
    animation08(g)
  Else
    g.ClearRectangle(0, 0, Width, Height)
  End If
End Sub

How It Works

1. The animation uses a phase-based system where each dot is offset in its animation cycle.
2. The dots scale up and down based on their current phase.
3. A timer drives the animation by incrementing the phase and triggering redraws.
4. The dots are positioned horizontally with equal spacing around the center.
5. Each dot’s size is calculated based on its current phase in the animation.

Using the Animation

To use this animation in your project, all you have to do is simply drag and drop the class on a DesktopWindow and then start or stop the animation when needed.

// Start the animation
SpinKit1.StartAnimation()

// Stop the animation when done
SpinKit1.StopAnimation()

Customization

You can customize the animation by adjusting:

• dotSize for larger or smaller dots
• dotSpacing to change the spread of the dots
• animationSpeed to make it faster or slower
• kDefaultColor to change the dot color
• kPhaseIncrement to adjust the animation speed

Taking It Further

The “Three Bounce” animation we’ve created is just one of many amazing animations in the SpinKit collection. Now that you understand the fundamentals, why not try recreating other SpinKit animations? Here are some exciting challenges to tackle:

• Modify the current animation to use different shapes (squares, rectangles).
• Experiment with different timing functions for varied animation effects.
• Try implementing the “Rotating Plane” or “Chasing Dots” animations from SpinKit.
• Create your own unique variations by combining what you’ve learned.
• Optimize the class further.

Share Your Creations!

Have you created an awesome variation or implemented another SpinKit animation in Xojo? Share it with the community! The Xojo Forums and social media are great places to showcase your work and inspire others.

Resources for Further Exploration

• Original SpinKit animations by Tobias Ahlin: https://tobiasahlin.com/spinkit/
• Xojo Graphics documentation: https://documentation.xojo.com/api/graphics/graphics.html
• Xojo DesktopCanvas documentation: https://documentation.xojo.com/api/user_interface/desktop/desktopcanvas.html

Remember: Every great application deserves great animations and now you have the tools to create them! Keep experimenting, keep creating, and most importantly, keep animating!

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

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

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 will work on Desktop and iOS projects by only copying and pasting the code, but you will need to make some changes to the example project for the Web version because of the need to convert Picture to WebPicture and back.

Download the Example Project from this link.

As you probably know, Method Extensions need to be created in a Module, so once you have created your new project, add a new Module to it (name it PictureExtensions) and, then, add a new method to the Module using the following signature:

• Method Name: Rotate
• Parameters: Extends SourcePicture As Picture, Optional ClockWise As Boolean = True
• Return Type: Picture
• Scope: Global

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

Var p As New Picture(SourcePicture.Height, SourcePicture.Width)
Var g As Graphics = p.Graphics

Var tRotation As Double = (90 * 3.14159 / 180) // 90º in radians
If Not ClockWise Then
  tRotation = -tRotation
  g.Translate(0, g.Height)
Else
  g.Translate(g.Width,0)
End If
g.Rotate(tRotation)

g.DrawPicture(SourcePicture,0,0)

Return p

And that is all!

Testing the Rotation

Now, let’s create the user interface (UI) to test it (in this case, a Desktop Project), but you can follow the same steps for an iOS project.

First, drop into the Navigator any image you want to use as the source. In this example it is named “Test”.

Now, select the Window1 window to access the Layout Editor and drag to it an ImageViewer control from the Library. Use the resizing handles of the ImageViewer added to the Layout Editor so it looks like the one shown in the following screenshot:

With the ImageViewer still selected in the Layout Editor, change its Name to “PreviewImageViewer” in the associated Inspector Panel, and make sure that the four locks under the Locking section are locked. Also, select the image “Test” as the image to be shown in the Image option found under the Appearance section.

Next, drag two buttons from the Library and drop them below the PreviewImageViewer control. The finished UI should look like the one in the following screenshot:

As you can see in the previous image, label the rightmost button as “Clockwise” and the leftmost one as “Counter Clockwise”.

Double click the “Clockwise” button and add the “Pressed” Event Handler to it. Next, add the following line of code to the associated Code Editor:

PreviewImageViewer.Image = PreviewImageViewer.Image.Rotate

Double click the “Counter Clockwise” button to add the “Pressed” Event Handler to it. Next, add the following line of code to it in the associated Code Editor:

PreviewImageViewer.Image = PreviewImageViewer.Image.Rotate(False)

Running the App

Run the example project and click (or tap) the buttons, you will see how the image rotates 90º clockwise or counter clockwise depending on the button clicked!

As you can see, we only needed a few lines of Xojo code to achieve this and this same code will work both on Desktop and iOS projects!

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

Fillings and Drawing with Brush

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

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

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

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

ClipToPath

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

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

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

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

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

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

Clip: New Graphic Contexts

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

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

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

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

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

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

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

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

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

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

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

DrawObject

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

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

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

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

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

Var d As New PDFDocument

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

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

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

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

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

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

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

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

Var x As Integer

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

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

// Transparency value = 0
Var tLevel As Integer

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

Var txt As String = "Transparency"

g.FontSize = 90
g.Bold = True

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

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

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

// Setting the initial random color for drawing
// the first rectangle
Var rd As New Random
g.DrawingColor = Color.RGB(rd.InRange(0,255), rd.InRange(0,255), rd.InRange(0,255))

Var tmpLevel, y1 As Integer

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

  // Setting the Transparency value
  g.Transparency = tLevel

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

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

  tmpLevel = tLevel

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

  // Drawing the color drops for the current Rect
  For i As Integer = 0 To 10
    tmpLevel = tmpLevel - 10
    If tmpLevel >= 0 Then
      g.Transparency = tmpLevel
      g.FillRectangle x,y1,2, 2
      y1 = y1 + 2
    End If
  Next i

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

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

  // we reached the maximum allowable value for
  // the transparency, so let's invert the sign
  // for the offset and set a new
  // drawing color.
  If tLevel = 100 Or tLevel = 0 Then
    offset = -offset
    g.DrawingColor = Color.RGB(rd.InRange(0,255), rd.InRange(0,255), rd.InRange(0,255))
  End If

Next n

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

// Notice that we are setting here the alpha value for
// the color, instead of relying on the Transparency property
g.DrawingColor = Color.RGB(255,255,255,127)

g.CharacterSpacing = 20
txtX = g.Width/2 - g.TextWidth(txt) /2
txty = y + 20 + g.FontAscent/2
g.DrawText txt,txtx, txty

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

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

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

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

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

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

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

Transparency vs. Color’s Alpha Value

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

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

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

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

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

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

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

or

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

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

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

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

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

And the PDF document created with Xojo 2021r3:

Document Size vs Image Quality

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

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

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

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

First off, you can now use the CharacterSpacing property to adjust the text tracking:

Next, you can create outlined text in your PDF documents by setting the Outline property to True:

It is now possible to use the LineDash method and the LineDashOffset property on the rendered text in combination with lines, paths and other shapes likes ovals and rectangles. You can also use these in combination with the LineCap and LineJoin properties, like you can do with the regular Graphics class:

It’s even possible to use the SaveState and RestoreState methods in order to save and retrieve the graphics state values.

Check out the useful ClipToRectangle method in your PDF documents. With it, all the drawing (rasterization of text, paths and shapes) will be restricted to the inside of the rectangle designated as the clipping area:

And if you need symbolic glyphs, you’ll find that using the ZapfDingbats and Symbol fonts will be very helpful in order to keep full vectorial resolution at any size you may need:

Also important, is the new addition that lets you to create a PDF document composed of multiple page sizes, using NextPage (width As Integer, height As Integer):

Lastly, now it is possible to retrieve the full PDF data from the document as a MemoryBlock using the ToData method. This is very useful in cases where you don’t need to save the PDF document to a file in first place, like when you are displaying the PDF document in a web app.

Questions? Ask me on Twitter @XojoES or on the Xojo Forum.

The Rotate method rotates drawing by the specified angle (in radians). The code below rotates the drawing area 45 degrees and draws a square so it will look like a diamond:

// Rotate the entire drawing area around its center
// and draw a rectangle
Const Pi = 3.14159
g.Rotate(Pi / 4, g.Width / 2, g.Height / 2) // 45 degrees or 1/8 of a circle
g.DrawingColor = Color.Blue
g.FillRectangle(g.Width / 2 - 20, g.Height / 2 - 20, 20, 20)

You can use Translate to change the origin point for drawing. Used in combination with Rotate, this code rotates a square around a center point:

// Rotate square in center of graphics area
Const Pi = 3.14159
g.Translate(g.Width / 2, g.Height / 2)
g.Rotate(Pi / 4) // 45 degrees or 1/8 of a circle
g.DrawingColor = Color.Blue
g.FillRectangle(10, 10, 50, 50)

With a few tweaks and a Timer, you can animate this (download project):

SaveState and RestoreState do what their names imply. They let you save the state of the graphics area so it can be restored later. SaveState can save this information:

• Translate
• Clip region
• PenSize
• AntiAliased
• DrawingColor
• Font
• Underline
• Rotate (rotation)

This code draws a blue rectangle, saves the state and then draws a red rectangle. It then calls RestoreState which puts the color back to blue and draws another blue rectangle:

g.DrawingColor = Color.Blue
g.FillRectangle(10, 10, 20, 20)
g.SaveState
g.DrawingColor = Color.Red
g.FillRectangle(50, 50, 20, 20)
// Restore to state where FillColor is Blue
g.RestoreState
g.FillRectangle(10, 50, 20, 20)

You might find that these new methods can serve as an alternative to Object2D for certain types of graphics drawing.

There are also other new Graphics features in 2021r1, such as Scale and Outline, which you can read about on the Graphics doc page.

You aren’t restricted to using solid lines anymore as the outline in the drawing of lines, rectangles, circles, ovals or paths anymore. From now on you can set the LineDash property of your choice, you can even set the LineDashOffset property and the LineCap and LineJoin from the supported types.

Moreover, the drawing fill is no longer limited to a solid color! The Graphic class includes now the Brush property, so you can create any of the supported brushes and assign any of them to it. For example, you can create color gradients really easy creating new instances from the LinearGradientBrush, RadialGradientBrush and assigning these to the Brush property. Of course, you can set as many GradientStops on these with the desired color to create the transition from one color to other in your gradient at given points during the filling process.

And, even better, you’re not restricted to using solid colors or gradient colors when you fill an object. Use the new PictureBrush class to assign the Picture you want to use for the fill and even the fill mode: Pad, Tile or Mirror.

Further, you can now give your text or shapes a shadow using the ShadowBrush property in the Graphics class, and the ability to create new instances from the ShadowBrush class.

In fact, when you use the default constructor of the ShadowBrush class, you’ll get an object right to use with a default color, offset for the X and Y coordinates and by default blur amount. Of course you can set any of these properties as you need for your ShadowBrush instances!

Questions? Ask me on Twitter @XojoES or on the Xojo Forum.

The best thing is that implementing this feature in your Xojo Web projects is really easy to do, and extremely flexible to set-up! Just drag and drop the WebChart control from the Library to your page (or ContainerControl) layout, set the Mode (type) of the chart you want to use and other properties in the Inspector Panel and you’re almost done.

Then, add your DataSet instances for your chart to display. Every one of these DataSets just needs to receive the Label to use, the data to display and the colors associated with each value or datapoint. For example, the following snippet of code creates a new WebChartCircularDataSet (WebChartLinearDataset and WebChartScatterDataset are other DataSet classes available, each of these use their own set of parameters in the Constructor):

Var sales() As Double = Array(12500.0, 30200, 25600, 15800)
Var colors() As Color = Array(Color.Orange, Color.Brown, Color.Purple, Color.DarkGray)
Var ds As New WebChartCircularDataset("Test", sales, Colors)

Every DataSet can be configured so it can fill or not fill the graphical object in the chart representing the value, and also associate another object with it via the usual Tag property.

Once we have a DataSet in place, we can add it to the chart simply calling the AddDataSet method on the WebChart instance. You can also add it to a specific position index or even remove a DataSet from the currently available ones in the WebChart instance. In this case T is the variable pointing to a WebChart:

T.AddDataset(ds)

Of course it is also possible to add labels to the WebChart itself. For example, if our DataSet has a total of four values, then we probably would want to add the same amount of labels to the chart instance:

T.AddLabels("Q1", "Q2", "Q3", "Q4")

In addition, one visually appealing thing is that the WebChart instance will animate the presentation of the dataset values; something it will do again every time we add a new DataSet to it. It is also possible to disable this behavior for the WebChart both via code and using the Inspector Panel.

Of course, you can add new DataSets to the WebChart once it is already shown in the webpage if you need to. But what you can’t do at runtime is changing the Mode (or type) of the WebChart itself. That is, if you did set a WebChart instance with the Mode set to Line, then you can’t change the mode via code to Bar.

All in all, I really think this is one of the (many) exceptional features introduced with Web 2.0 that will make your web apps shine even more and without much effort! Definitively, the icing on the Pie.

Questions? Ask me about Xojo programming on Twitter @XojoES or on the Xojo Forum.

One solution is to use a GraphicsPath to draw exactly what you want. With a GraphicsPath you can use the AddArc() method to add rounded corners and then draw the lines for the rest of the rectangle.

This is the code for desktop:

Const Pi = 3.14159
Const x = 50
Const y = 00
Const rectHeight = 100
Const rectWidth = 100
Const arcRadius = 20

Var topRoundRect As New GraphicsPath
topRoundRect.AddArc(x, y, arcRadius, Pi, 1.5 * Pi, False)
topRoundRect.AddArc(x + rectWidth, y, arcRadius, 1.5 * Pi, 0, False)
topRoundRect.AddLineToPoint(x + rectWidth + arcRadius, rectHeight)
topRoundRect.AddLineToPoint(x - arcRadius, rectHeight)
topRoundRect.AddLineToPoint(x - arcRadius, y)

g.DrawPath(topRoundRect)

You’ll want to tweak the numbers to fit your situation, but this should give you the idea.

With a couple minor tweaks¹, the same code also works on iOS. Change GraphicsPath to iOSPath and change the AddLineToPoint() method calls to LineToPoint(). This is the result:

GraphicsPath maps very closely to HTML5 Canvas Path so you can often find code samples online that are easily adapted to Xojo. For example, take a look at this JavaScript code from HTML5 Canvas Tutorial which draws a squiggle:

var context = canvas.getContext('2d');

context.beginPath();
context.moveTo(100, 20);

// line 1
context.lineTo(200, 160);

// quadratic curve
context.quadraticCurveTo(230, 200, 250, 120);

// bezier curve
context.bezierCurveTo(290, -40, 300, 200, 400, 150);

// line 2
context.lineTo(500, 90);

context.lineWidth = 5;
context.strokeStyle = 'blue';
context.stroke();

Notice how similar the JavaScript looks to the equivalent Xojo code that draws the same squiggle:

Var path As New GraphicsPath
path.MoveToPoint(100, 20)

// line 1
path.AddLineToPoint(200, 160)

// quadratic curve
path.AddQuadraticCurveToPoint(230, 200, 250, 120)

// bezier curve
path.AddCurveToPoint(290, -40, 300, 200, 400, 150)

// line 2
path.AddLineToPoint(500, 90)

g.DrawingColor = Color.Blue
g.DrawPath(path)

¹ As we mentioned in the Xojo 2020 Update video and in our Roadmap, the iOS API is planned to match the API used by other platforms so you won’t need slightly different code here in the future.

You may already know that in order to create a Method Class Extension, you need to add a new method to a Module. For example, you can create a new Module and name it “Graphic Extensions”.

Then add a new Method to it using the following signature:

• Name: CenterPicture
• Parameters: Extends g As Graphics, Image As Picture
• Scope: Global

Add the code that will position and scale the received picture on the Graphic area:

// Let's check first that the referenced Picture is not nil
If Not (image Is Nil) Then
  
  Var Height, Width As Integer
  Var SourceY, SourceX As Integer = 0
  
  //If the Image width and Height just fit inside the Graphic area
  //then there is not need to scale it.
  If image.Width <= g.Width And image.Height <= g.Height Then
    
    Width = image.Width
    Height = image.Height
    
  Else
    
    // Else, let's scale the image when its width is greater
    // than its height
    If g.Width >= g.Height And image.Width >= image.Height Then
      
      Width = g.Width
      Height = (Image.Height * Width) / image.Width
      
      
      //…recalculating its width if the new height is greater
      // than the height of the current Graphics context
      If Height > g.Height Then
        
        Height = g.Height
        Width = (image.Width*Height)/image.Height
        
      End If
    
    // let's scale the image when its width is less than its height
    // but the width of the graphics context is greater than its height
    Elseif g.Width >= g.Height And image.Width <= image.Height Then
      
      Height = g.Height
      Width = (image.Width * Height) / image.Height
    
    // scale the imagen when the width is greater than its height
    // and the width from the Graphics context is less than its height  
    Elseif g.Width <= g.Height And image.Width >= image.Height Then
      
      Width = g.Width
      Height = (image.Height * Width) / image.Width
    
    // lastly, this is the case when both the image and Graphics width 
    // is less than its respective heights.  
    Elseif g.Width <= g.Height And image.Width <= image.Height Then
      
      Height = g.Height
      Width = (image.Width*Height)/image.Height
      
      // It may be the case that the new calculated width is greater
      // than the available width in the Graphics context,
      // so we adjust the scale on the max width for the image.
      If Width > g.Width Then
        
        Width = g.Width
        Height = (image.Height*Width)/image.Width
        
      End If
      
    End If
    
  End If
  
  // Let's calculate the X and Y coordinates in order to
  // display the image centered on the Graphics context
  sourcex = (g.Width/2) - (Width/2)
  sourcey = (g.Height/2) - (Height/2)
  
  // and we draw finally the picture in the Graphic context
  // using the new calculated values
  g.DrawPicture(image,sourcex,sourcey,Width,Height,0,0,image.Width,Image.Height)
  
End If

And that’s all.

From now on, you can call this method from the Paint Event Handler of a Canvas subclass, or the Graphics context of another Picture using:

g.CenterPicture(mImage) // mImage is a valid instance of a Picture

Of course, you can go ahead and add other useful method extensions to your own Graphics Extensions module.

The available methods in the class give you the ability to create any shape you need in an easier way when compared with the Object2D class (and other classes you may use in combination), from simple rectangles (including the “rounded” variation), to arcs, curves or quadratic curves (Bézier curves) where we model them through a control point.

The interesting thing in GraphicsPath is that every call to any of these methods have the starting coordinate the ending point of the previous shape in the path, while you can use the MoveToPoint method in order to, well, move the virtual “cursor” to any point of your election without painting anything in the process. Thus, this one would act as the starting (or initial) point for the next method drawing in the path.

As for the available properties, you can use these:

• CurrentPoint. Check this value in order to know the current coordinate, so you can make the proper decision about what to do next in your code.
• IsEmpty. This one allows us to know if the path is empty; this is, it doesn’t contain any shape definition in it.
• IsRectangle. This property is really useful to know if we are dealing with a rectangle shape in our GraphicsPath instance.

Starting your Path…

Let’s see how simply it is to apply these principles during the creation of a graphic making use of a Bézier curve, and the best part is that this example project lets us move that control point, so you can make a better idea about how it goes. This is the final look of our example application:

1. Designing the User Interface

The user interface for our example app is quite simple, with a few controls in it:

• 2 Labels
• 2 Sliders. Use the Inspector Panel on them to activate the “Allow Live Scrolling”, under the Behavior section.
• 1 Canvas control.

Set the Locking properties in the Inspector Panel for the Sliders and the Canvas, as shown in the picture. This will allow the controls to properly resize when the Window size is changed by the user.

2. Creating your own Graphic Canvas (Canvas subclass)

We need the Canvas to be specialized, so that means that we need to subclass the Canvas class and put in all the specific stuff we may need.

Add a new Class to the project (Insert > Class), and access the Inspector Panel to change the values of the following properties:

• Name: CuadraticCanvas
• Super: Canvas

Next, add two Computed Properties. For that, make sure you selected the just added class in the Navigator, and access the contextual menu to choose the Add to “CuadraticCanvas” > Computed Property option.

Change the following fields in the associated Inspector Panel:

• Name: PC1X
• Type: Double

Next, choose the “Set” method on the Computed Property and add this single line of code after the existing one:

invalidate

This will force our canvas to redraw itself every time we change the value of the X point in the coordinate of our Bézier curve.

Repeat the operation in order to add a second Computer Property, using the following values this time:

• Name: PC1Y
• Type: Double.

Remember to add the “Invalidate” line of code to the “Set” method on this property too.

Now is time to add the Paint Event Handler to our class. For that, and with our class item still selected on the Navigator, access the contextual menu and choose the Add to “CuadraticCanvas” > Event Handler option.

In the resulting panel, select the Paint entry from the left list and confirm the selection. The last action will add the new event to the class, bringing the associated Code Editor. Write the following code snippet:

g.AntiAlias = True

g.DrawingColor = &cffffff
g.FillRectangle(0,0,g.Width,g.Height)
g.DrawingColor = &c000000
g.DrawLine(g.Width/2,0,g.Width/2,g.Height)
g.DrawLine(0,g.Height/2,g.Width,g.Height/2)

g.DrawingColor = &ccc1233

Var gp As New GraphicsPath
gp.MoveToPoint(0,g.Height/2)
gp.AddQuadraticCurveToPoint(Me.pc1x,Me.pc1y,g.Width,g.Height/2)

g.DrawPath gp

As you can see, here is where we create our GraphicsPath instance (the “gp” variable) so we can use it to add the quadratic curve using as the control point the values of our “PC1X” and “PC1Y” properties.

In order for our GraphicsPath instance to be drawn in the graphical context (the “g” parameter), we need to use the DrawPath method passing along our “gp” object as argument.

3. Joining the Points

Choose the “Canvas1” item in the project Navigator and access the Inspector Panel so you can change the “Super” value to “CuadraticCanvas”.

Next, select the “Slider1” item and add the “ValueChanged” Event Handler to it. Write this line of code in the associated Code Editor:

canvas1.pc1x = me.Value

Repeat the operation with the “Slider2” item, except that this time you need to change the line of code slightly:

canvas1.pc1y = me.Value

We are almost done! Select now the “Window1” item in the project Navigator and add these two events to it: Open and Resizing. Write this line of code in both event handlers:

SetSliders

Finally, we will add a new method to the Window1 item. For that, select the Window1 item in the project Navigator (if it is not yet selected), and access the contextual menu in order to choose the Add to “Window1” > Method option. Make use of the Inspector Panel to reflect this method signature:

• Method Name: SetSliders

And write the following code snippet in the associated Code Editor for the method:

slider1.MaximumValue = canvas1.Width
slider2.MaximumValue = canvas1.Height
canvas1.PC1x = Slider1.Value
canvas1.PC1y = Slider2.Value

This will be the method in charge of updating the maximum value of the sliders to the width and height of the window, and also to update our canvas control properties forcing it to redraw itself with the new values.

In Good Shape!

We have everything set now. Run the app and use the sliders to move the Bézier curve control point. As you change the sliders values, you’ll see how the curve smoothly updates its shape in the canvas.

You have a starting point now! Try to use the other methods available in the GraphicsPath class in order to make more complex drawings in your own apps!

Download the example Xojo Project

Please run a current Xojo version with MBS Xojo Mac64bit Plugin installed. Due to our dependencies list, please add Main, MacCloud, MacBase, MacCocoa, MacControls, MacCG and MacCF plugins too. Start with a new project. To the window we add a SCNControlMBS control from the library and rename it MyControl. Drag it across the entire window size and lock all edges. It is very useful because we want fullscreen mode later. 

Then we need two properties MyScene and MyView. MyScene has the type SCNSceneMBS and MyView has the type SCNViewMBS. Afterwards, add the open event of the SceneKit control. 

We start with the setting of MyView and MyScene like this:

MyView = Me.View 
MyScene = New SCNSceneMBS
MyView.scene = MyScene

Then we enable the default light and the camera control, because we want to see a 3D effect and want to move the camera using the mouse. We set black as the background color.

myView.autoenablesDefaultLighting = True  
MyView.allowsCameraControl = True   
myView.backgroundColor = NSColorMBS.blackColor 

Next we add our first node to the scene. The center of the scene is the Sun. In basic structure the Sun is a lit up sphere. So we add a sphere geometry with a given size. In this project we can’t work with the original conditions, because Mercury would be so small that it is impossible to see. Plus, we would have same problem for the distance between the Sun and the planets. Because that, our Sun has a radius of 13. Then we add a node and give it geometric information about the Sun. The position of the node is the origin with the coordinates 0,0,0. Finally, we add the node to our scene. 

Dim SunGeometry As New SCNSphereMBS(13)  
Dim Sun As New SCNNodeMBS(SunGeometry)  
Sun.Position = New SCNVector3MBS(0, 0, 0)   
MyScene.rootNode.addChildNode(Sun)

Then we start our program. 

We see a white sphere on the screen. The Sun looks a bit edged because of the segment count. Our Sun sphere is very big and needs more segments then the default segment count. Set the segment count property ahead of adding the node to the scene command. 

	SunGeometry.segmentCount=100 

Then we set each planet in a similar way. Because the planets look different, we want to change their colors as appropriate or even put a picture as a graphic over each sphere. For the color of an object we have the firstMaterial.diffuse.contents Property. This is how you would set a gray color for Mercury. 

 MercuryGeometry.firstMaterial.diffuse.contents = NSColorMBS.grayColor

If we want to map a picture on a geometry, for example for Earth, we add this picture to our project and set it to the geometry. It’s a bit like covering it with a blanket with a high percentage of elongation. We can imagine that by covering a sphere, we stretch the blanket on the equator more than on the polar caps. Because that, if you look on a map, the longitudes and latitudes are not parallel, but rather bent. In reality the longitude and latitude are parallel. You can see that on a globe. Fortunately for us a world map is already a perfect UV map for a sphere. Thanks to the website www.ginkgomaps.com which supplies world maps to everyone. I used one of these maps in my example. You can customize the map with a graphic program. Then add it to the project and set it in the property. 

Dim EarthGeometry As New SCNSphereMBS(1.47)  
EarthGeometry.segmentCount=100  
Dim Earth As New SCNNodeMBS(EarthGeometry)  
EarthGeometry.firstMaterial.diffuse.contents = EarthPic  
Earth.Position = New SCNVector3MBS(25, 0, 0)   
MyScene.rootNode.addChildNode(Earth)

All other textures I draw myself in a graphic program.

For the position of the Planets, we must pay attention to the fact that the origin of the single planets are in the center of the sphere and we set in the constructor of the geometry as the radius and not the diameter. The distance between two planets are: radius of planet 1+radius of planet two+ space between them. 

Following this same pattern we add the other planets. Saturn has a planetary ring. The ring is a tube with an inner radius that is bigger than the planet and a small hight. I use the same structure on the ring as on the planet. The tube is a bit rotated. We rotate the ring a bit by x and y. The specification of a rotation looks like this: 

saturnRing.orientation = New SCNVector4MBS(-0.4, -0.5, 0, 1)

Let’s Move the Solar System

Now we want to move the Scene. We assume that the planets’ orbits are all parallel to the xz plane and that they are exactly circular. To roate around a certain point, we create a geometry for each rotation. It lies in the point and is a parent node of the geometry. If a parent node moves, a child node moves too. The inverse does not apply. In that way, if we rotate the helping node in the origin, the child node moves around the origin too. We cannot use the Sun as the parent node for all planets because the planets are supposed to move at different speeds. 

The creation of the geometry looks similar for each planet:

Dim UranusRotationGeometry As New SCNSphereMBS(1)  
Dim UranusRotation As New SCNNodeMBS(UranusRotationGeometry) 
UranusRotation.Position = New SCNVector3MBS(0, 0, 0)  
MyScene.rootNode.addChildNode(UranusRotation) 

UranusRotation.addChildNode(Uranus) 

These geometries are covered by the Sun. 

Then we add the movements. We defined a rotation of the helping node and set the information about the rotation. We want to rotate around the y axis in each cycle about 360°. The information is given in the unit rad. Because of this we must convert 360° to 6.283 rad. The last parameter is about the speed of the operation. In this section we can set the proportion of the speed of the planets. The speed of Earth is the basic value. Everything is based on this value. The assumption is: an Earth year lasts 365 days. For each planet we use the number of Earth days a planet takes to rotate once around the Sun. We divide this value by the days of an Earth year. For Neptune we get a value that is approximate to 164.79 rad. That we can multiply with a variable. The variable can be set by the customer to regulate the speed of the solar system. We want to repeat this movement again and again. In this way we set it. In the last step we set this rotation to the scene.  

Dim moveNeptune As SCNActionMBS = SCNActionMBS.rotateBy(0, 6.283, 0, 164.79 * speed)
Dim Neptunerepeat As SCNActionMBS = SCNActionMBS.repeatActionForever(moveNeptune)
NeptuneRotation.runAction(Neptunerepeat)

Finally, we want to talk about lighting. The Sun is the light source. It is a light that comes from a point and shines in all directions. That type of light source is called an omni light. We define a light as a property from a node. Since our Sun is a node in the scene, we add the light property directly. All nodes that spray light don’t get any light and they are normally black. With the emission property we can make the sphere look like it is glowing. We choose yellow as color. 

Dim SunGeometry As New SCNSphereMBS(13) 
Dim Sun As New SCNNodeMBS(SunGeometry) 
sun.Light = New SCNLightMBS 
sun.Light.Type = SCNLightMBS.SCNLightTypeOmni 
sun.Light.Intensity = 2000
sun.light.Color = NSColorMBS.whiteColor sun.Light.Intensity = 2000 SunGeometry.firstMaterial.emission.contents = NSColorMBS.yellowColor SunGeometry.segmentCount = 100 
Sun.Position = New SCNVector3MBS(0, 0, 0)  
MyScene.rootNode.addChildNode(Sun)

The scene seems very dark if the Sun is our only light source, so add weak ambient light that lights up all elements in the same way. The unit of the light intensity is lumen. Now you can run the project and admire your own programmed solar system. Have a lot of fun with that. Link to project.

If you have questions about SceneKit don’t hesitate to contact me. And please join my session about SceneKit at the XOJO.CONNECT conference in Nashville.

Download the project.

Stefanie Juchmes studies computer science at the University of Bonn. She came in touch with Xojo due to the work of her brother-in-law and got a junior developer position in early 2019 at Monkeybread Software. You may have also read her articles in Xojo Developer Magazine. 

Since the early days there has been the feature request to use the graphics class in Xojo to draw to a PDF document. We recently came back to this old feature request and decided to try a new way to implement it and our new code seems to work just fine. With some help from Xojo engineers, we even got the alignment right.

At the Xojo Developer Conference 2019 in Miami in the presentation about news in MBS Xojo Plugin, Christian Schmitz presented this new feature. We can draw the normal drawing commands for lines, rectangles, polygons and pictures, but also text and even vector graphics. With the support of vector graphics, you can even use the report engine in Xojo and let it output your reports as PDF documents.

In your project, you can have a central draw(g as graphics) method, which handles drawing your content. For a print preview, you can let it draw to a picture and show the picture scaled down in a canvas. The same code can be called for drawing to a graphics object from printer received via OpenPrinterDialog function. And for saving as PDF, you can use the graphics object from DynaPDF. Just query PageGraphics object while you have a PDF page open.

Here is a code example:

Dim pdf As New DynapdfMBS
Dim f As FolderItem = SpecialFolder.Desktop.Child(“DynaPDF Graphics.pdf”)

// For this example you can use a Starter, Lite, Pro or Enterprise License
‘pdf.SetLicenseKey “Starter” 

// Create new PDF. Use f = nil for in-memory PDF
Call pdf.CreateNewPDF(f)

// append a new page, so we have an open page
Call pdf.Append 

// get graphics object to draw on the page
Dim g As Graphics = pdf.PageGraphics

// draw as usual
g.DrawString “Hello World”, 105, 100
g.DrawRect 100, 80, 100, 100

// close page and file
Call pdf.EndPage 
Call pdf.CloseFile

// for in-memory PDF, use GetBuffer here to grab it.
‘Dim PDFData As String = pdf.GetBuffer

As you see, we use normal drawing commands for adding text to the page. A few lines are needed to setup the PDF environment and after drawing to properly close the file. If you like to customize the new PDF pages, you can implement NextPage event on DynaPDFMBS class and for example import an existing PDF document as letter paper for your background. You should also implement Error event to handle any problem while creating the PDF document. 

Depending on your DynaPDF license, other features like rendering PDF Pages, importing of other PDF pages or digital signatures may be possible. But even with starter license, you can create new PDF documents and draw into them. If you have questions, please do not hesitate to contact Monkeybread Software.

Christian Schmitz has been active in the Xojo community for over 20 years. As the developer behind the Monkeybread Software Plugins he provides thousands of classes and example projects to help you build better applications with Xojo. In Europe, Christian has organized over 10 conferences, including the upcoming conference in Cologne this fall. You may have also read his articles in Xojo Developer Magazine. DynaPDF and other MBS plugins are available in the Xojo Add-Ons Store and at Monkeybread Software.

Starting with Xojo 2018r3, this Graphics property was removed from Window and Canvas so if you had code that was still relying on it, that code will no longer compile. Here are some tips on how you can migrate your code to use the Paint event handlers and tell the Canvas to update with a call to Invalidate.

If your code was simple and just drawing a Picture to the Graphics property, then you would just move the code to the Paint event handler. For example, this code is drawing a picture:

Canvas1.Graphics.DrawPicture(MyPic, 0, 0)

Where that code existed, you would tell it to redraw Canvas1:

Canvas1.Invalidate(False)

And then in the Canvas.Paint event handler you would draw the picture:

g.DrawPicture(MyPic, 0, 0)

Related to this is another thing to keep in mind. Do not use this Graphics object (g) outside the lifetime of the Paint event. You can certainly pass the Graphics parameter from the Paint event to other methods, but you should not keep a reference of it in a property or elsewhere. When the Paint event eventually completes, this Graphics object is no longer valid and the copy you’ve saved in a property also becomes invalid. Attempting to use a saved Graphics object outside of the Paint event’s lifetime may raise an exception in future versions of Xojo.

For more information and other strategies to handle more advanced situations, refer to the topic in the documentation: Updating Code That Used the Graphics Property

I’ve had many people ask for an example for how to create a Canvas that allows you to:

• Draw pictures within it (as objects)
• Move these objects
• Remove them
• Add labels to them
• Programmatically select one

This example demonstrates how to do all these things. It has a large Canvas on the window with several buttons that let you add and manage the objects on the Canvas.

Use the SegmentControl to select the type of object you want to add to the Canvas and click the Add Object button.  You can optionally specify text to label the object using the field below the button.

Add as many objects as you want. You can click to select an object and it will have a black border drawn around it. You can drag any object within the Canvas.

The other buttons center or remove a selected object.  You can use the Select Object # button to select the object number you specify (objects are numbered starting at 0).

About the Project

The concept is pretty simple. Essentially you have a class that represents objects to draw on the Canvas and that knows how to draw itself on a Canvas.

In this project, the CanvasObject class represents an object to draw on the Canvas. It contains everything it needs to know to draw itself, such as its coordinates, label text, the icon to display and other properties.

The ObjectContainerCanvas class is a subclass of Canvas that is responsible for all the drawing, moving and removing of CanvasObjects. This class has an array of CanvasObjects that it knows about. The objects in this array are drawn by the Canvas Paint event handler when appropriate by calling the Draw method on the object itself.

To allow you to drag an object within the Canvas, the MouseDrag event handler is used. It knows what the currently selected CanvasObject is and as you drag the mouse, it updates the coordinates for the CanvasObject.

When the Canvas is told to update itself, usually through a call to Invalidate, the Paint event is called. Here each CanvasObject in the array is drawn on the screen.  This is the Paint event:

If Background <> Nil Then
  g.DrawPicture(Background, 0, 0)
End If

For Each co As CanvasObject In mCanvasObjects
  co.Draw(g)
Next

The CanvasObject’s Draw method draws itself at its coordinates and also draws a selection rectangle around itself if it is selected. This is the Draw method:

// Draws the object on the canvas.
g.DrawPicture(Image, Left, Top)

If Selected Then
  Const kBorder = 2
  // Draw selection rectangel around the image
  g.PenHeight = kBorder
  g.PenWidth = kBorder
  g.ForeColor = TextColor
  g.DrawRect(Left - kBorder, Top - kBorder, Width + kBorder * 2, Height + kBorder * 2)
End If

In addition, ObjectContainerCanvas has two events that are called when an object is selected (ObjectSelected) and when an object is moved (ObjectMoved).

Download the ObjectsInCanvas example.

Check out the other methods on ObjectContainerCanvas that are used to add, move, remove and select objects. I hope you find this technique useful in your projects.

Along the way, we also will see how the Xojo IDE simplifies making subclass properties available from the Inspector Panel, so when using their instances we can set some attributes as the background color, pen size or border color in a more convenient way.

As usual, the first step to create a new subclass is adding a new class item to the Desktop project (Insert > Class). With the new class item selected, change its name to something descriptive. For this example we will use MyImageWell. The most important thing here is setting Canvas as its Super attribute. That means that the subclass will be based on the Canvas class, inheriting all its properties, Events and Methods so they will also be available for the subclass.

One of these inherited Events is Open, and we will implement it using the Event Handler option (click the + button in the toolbar to access the dropdown menu) in order to inform the class that we want to accept the dropped JPEG files. This is done with the following line of code in the Open Event Handler:

Me.AcceptFileDrop("img/jpeg")

Obviously, we can extend this support to accept other Xojo compatible graphical formats. For that, we would add a new File Type Set to the project, using it as the filter in the previous line of code.

Once we inform the class that we accept this feature, the next step is implementing the DropObject Event Handler that fires once this action is detected inside the limits of the control. The code we need to write for this Event Handler will test that the obj parameter passed along contains a valid FolderItem and, in that case, we will load such file as a new Picture object, assigning it to a property of the same Type. The code for the event is:

If obj.FolderItemAvailable Then
  image = Picture.Open(obj.FolderItem)
  Invalidate
End If

Don’t forget to add the Image computed property to the Class using Insert > Computed Property while the MyImageWell item is still selected, and using these values:

• Name: Image
• Type: Picture
• Scope: Public

As you can see, the amount of code we need to load the file as a Picture object and to assign it to the class property is minimal! Why do we use the Invalidate method call afterwards? Well, this is responsible for informing the operating system to redraw the instance when it has a chance. And when this happens it will fire the third and last Event we need to implement: Paint. Here is where we can instruct any Canvas based control how to draw itself through the graphical context represented by the g parameter passed along the Event.

Painting the control

Once we’ve added the Paint Event to the class and before writing the code responible of painting the dropped image inside its limits, we need to add three additional computed properties. We will use them to set some attributes like the color we want to use to paint the control background, the border color and even the width of the border:

• BackGroundColor As Color = &cdddddd
• BorderColor As Color = &c000000
• PenSize as Integer = 2

Add to the Setter method on every computed property the sentence me.invalidate; so every time we assign a new value to them… the control will be redrawn using the new value (background color, border color, pen size or even a new assigned picture).

The last step is writing the code responsible for drawing the control itself: filling the background with the set color, then drawing proportionally (and centered) the loaded picture pointed by the Image property, and finally drawing the border with the width and color specified. All of this is what we can do using the following snippet of code:

// We fill the control background using the set color
g.DrawingColor = BackgroundColor
g.FillRectangle(0,0,g.Width,g.Height)

// If we have a valid image object, then we draw it centered and scaled (if necessary)
If image <> Nil Then 
  Var Height, Width As Integer
  Var sourcey, sourcex As Integer = 0 
  If image.Height > image.Width Then
    Height = Me.Height
    Width = (Me.Height * image.Width) / image.Height
    sourcey = (Me.Width - Width) / 2
  Else
    Width = Me.Width
    Height = (Me.Width * image.Height) / image.Width
    sourcex = (Me.Height - Height) / 2
  End If

  // This is the line that actually draws a picture inside the graphic context of our instance
  g.DrawPicture(image,sourcey,sourcex,Width,Height,0,0,image.Width,image.Height)
End If

// We draw the control border
g.PenSize = me.PenSize
g.DrawingColor = BorderColor

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

As you can see, the code needed for this is also very simple!

Make the properties visible from the Inspector Panel

While we are on it, we can use the Inspector Behavior feature to make our specific properties visible through the Inspector Panel. This way, when we add new instances from the subclass to the layout of any window, we will be able to easily set their values directly from the Inspector Panel. With the MyImageWell item still selected in the Project Browser, use the contextual menu to select the Inspector Behavior option to access the following Window:

Here you will see all the Class properties, those common to all Canvas derived subclasses and also the ones added for us and that are specific to our class. You can find these properties listed under the Behavior section. To make them visible in the Inspector Panel we just need to check their associated checkboxes; and even modify their default values editing the associated cell if we want to.

Now, we just need to drag and drop the MyImageWell item from the Project Browser into any Window Design Layout in order to add new instances! Once we run the example project, we will see how the controls react to displaying any JPEG picture dropped on it.

If you want, you can investigate deeper into the methods provided by the Graphics class in order to make the control more glittery or more sophisticated.

You can watch this video (en español) to see this in action:

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers, Markdown Parser for Xojo, HTMLColorizer for Xojo and the Snippery app, among others

*Read this post in Spanish

The following tutorial is based on the Desktop Xojo project that you can download from this link. In fact, this project was the foundation to the search filed control implemented in the Snippery app. Thus, you can envision in more detail the kind of functionality you can achieve when used in a real app. Ok, maybe you are thinking “this is not the native control a user expects when using a true native app under certain OS”. That’s true; anyway there are a lot of apps around (some of them from the big players) that use non-native controls in favour of providing a unified UI between all supported platforms. This is the case of the final class exposed here, offering the same aspect and behaviour when running under macOS, Windows and Linux.

Preparing the Ingredients

In order to create our multiplatform search control we need to use a series of components (classes) that will cooperate with each other: a TextField that will receive the user keyboard input (that is, where the user inputs the text to search); a Canvas subclass to display the typical magnifying glass icon and other decoration for the control (that also extends further to add more functionality); and a second Canvas subclass that will offer the classic “search text clean” widget functionality normally presented at the right of a search field.

Of course, you can create a search field using these classes as individual items on a Window layout, but in that case all the resizing operations and cooperation between the controls will be more messy — losing the encapsulation that a ContainerControl provides to the other components of the application as if it was a unique, simple control.

Dealing with the Graphics

The resulting control uses three pictures for a total of two functions: one for the magnifying glass and two for the “text cleaning” widget that will be displayed only when the TextField has text on it. The widget has to change its image when the pointer is on it so the user can see that this is an active “clickable” control.

Fortunately Xojo eases the management of multiresolution pictures in our apps, changing on the fly between the existing regular/normal resolution and the HiDPI/Retina versions for the same given picture. Thus, we only need to use our favourite graphics editor app to draw and export the pictures with the required quality as PNG files (personally I use the Sketch on macOS).

In order for Xojo to be able to do its magic, you shouldn’t import the pictures to the app by dragging them from disk and dropping them on the Project Browser or Xojo will import the pictures as an alias. Instead, use the Insert > Image option to add an Image instance to the project, showing the associated Editor where you’ll be able to assign every picture file for the supported resolutions of a same graphic. Of course the label you use as the Image name on the Inspector Panel will be the name you use to reference the Image from code or when assigned to other controls properties. If you explore the example project for this tutorial, you can see the three Images used: searchIcon, CloseSelected and Close in regular and HiDPI/Retina resolutions.

Creating the Text Cleaning Widget

We have already seen in a previous tutorial (in Spanish) how easy it is to create custom graphic controls in Xojo based on the Canvas Class. In order to create the widget providing the search text cleaning feature, we will follow that same principle here:

• Add a Canvas subclass and name it CloseButtonClean.
• Add the Open, MouseEnter and MouseExit events to the subclass
• Type the following code into the Open event, basically to assign the picture showing its initial state and making it invisible:

me.Backdrop = close
me.Visible = false

• We will use the MouseEnter and MouseExit events to change the displayed picture in response to  the pointer cursor being inside or outside the limits of the control; showing that this is an active/clickable control. Put the following line of code in the MouseEnter event:

me.Backdrop = CloseSelected

• And the following one in the MouseExit event of the control:

me.Backdrop = close

We have completed the decoration of our little class, but it is also desirable to provide an external interface so other controls can easily change the state of the widget. We will do that by adding two methods to the class.

With the widget class still selected on the Project Browser, select the Insert > Method option twice to add two Methods and using the Inspector Panel to change the Method names to “Activate” and “Deactivate”, respectively. Leave the Scope as Public for both methods, so they are reachable by other objects and not only those created from the class.

The select method simply changes the control visibility to True:

me.Visible = true

While the Deactivate method will do the opposite action:

me.Visible = false
me.Backdrop = Close

Drawing the Search Control

The second of the required classes based on the Canvas class is no more complex. In this case we will not assign a picture to the Backdrop property of the Canvas, instead we will use the Paint event to directly draw the decoration, including the magnifying glass picture at the appropriate coordinates of the control.

So, after adding a second Canvas subclass to the project —named cSearchBackground in our Example project—, we just need to add the Paint event to it, writing the following lines of code on the associated Code Editor:

g.PenWidth = 1
g.PenWidth = 1
g.ForeColor = &caaaaaa
g.DrawRoundRect(0,0,g.Width,g.Height,5,5)
g.ForeColor = &cffffff
g.FillRoundRect(1,1,g.Width-2, g.Height-2,5,5)
dim midY as integer = (g.Height/2) - (searchIcon.Graphics.Height/2)
g.DrawPicture(searchIcon,5,midy)

In essence, we are drawing the control border using the provided foreground color (&caaaaaa, in hex notation), and filling the control background with the white color. After that, we will paint the magnifying glass icon using the DrawPicture method of the Graphic class provided as the drawing context for the Paint event.

Container Control: Putting it all Together

Once we have all the required items for our “complex” UI control, it’s time to add a ContainerControl to the project using the Insert > ContainerControl option. The first thing you probably notice is that the Layout Editor is very similar to the one used for designing the windows of the app. After all, the ContainerControl is about adding, resizing and aligning several UI controls on it, as you do when designing a window.

With the added ContainerControl still selected, change the attribute Name to ContainerSearchField on the associated Inspector Panel.

Now we just need to add an instance of our cSearchBackground class to the ContainerControl, a TextField control from the Xojo Library Panel and our search text cancelation widget class to the right of the just added TextField. The final layout of the control should be something similar to this (after adjusting the own Container Control height and width):

In order to correctly draw the control background when resizing the ContainerControl, select the cSearchBackground instance and add the Open event with the following line of code:

me.Width = self.Width

In addition, we also want that the TextField to show our search text cancellation widget only if the TextField has text on it. Select the TextField instance on the ContainerControl (searchField in the example project), and add the TextChange event with the following code in the associated Code Editor:

if me.Text <> "" then
  CloseButtonClean1.activate
else
  CloseButtonClean1.deactivate
end if

With the TextField still selected, set the CueText property under the Initial State section of the Inspector Panel to “Search”. This will be the text shown by default when the TextField is empty.

Of course we want to add functionality to the instance of our search text cancelation widget —named CloseButtonClean1 in the example project—. Add the MouseDown event and write the following line of code on the associated Code Editor:

searchField.Text = ""

When using a ContainerControl you will want to provide a way to resize every control inside of it in response to the resizing of the ContainerControl itself. We resolve this by adding the doResize method to our Container Control with the following code:

closeButtonClean1.Left = me.Width - 24

searchField.Width = (Me.Width - 27) - searchField.Left

cSearchBackground1.Width = me.Width

cSearchBackground1.Invalidate

As you can see this method simply does some calculations to reposition the controls based on their relative coordinates, updating also the width of the background control to reflect the same width of the ContainerControl itself. Finally it calls the invalidate method on the background instance class so the control can update the drawing.

In order to finish our ContainerControl subclass, we just need to add a couple of events: Open and Resizing. The first will be in charge of setting the initial state for the control, while the second will call the doResize method every time the ContainerControl is resized.

Once you’ve added these events, select them and simply write the call to the doResize method in both cases.

Using the SearchField ContainerControl

That’s all! You can start using the control by dragging it from the project browser to the Window Layout in order to create a new instance. Of course, we have not implemented the search functionality itself in this example project, mainly because it depends of the purpose of the final application itself. In addition, it would be easy for you to add extra functionality as text autocompletion as we have seen in a previous tutorial.

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers and the Snippery app, among others.

*Read this post in Spanish

*Watch the video in Spanish

The transition GDI to GDI+ to Direct2D

GDI is another Graphics API that was present in the initial release of Windows and to this day remains an integral part of the OS. However, since GDI is such old technology it lacks basic anti-aliasing support, alpha channel support, and still deals in integer coordinates. GDI+ was introduced in Windows XP and included everything missing from GDI, with one glaring issue, text rendering. While the appearance itself is slightly different (one of the original reasons why even with App.UseGDIPlus enabled Xojo still rendered DrawStrings using GDI text rendering), but also because of the additional text processing and resolution independence capabilities in GDI+, text rendering is performed by the CPU.

Direct2D/DirectWrite solves all those issues, and best of all it can still interoperate with GDI code which is important for Xojo Plugin developers and other parts of Xojo that still rely on a GDI graphics context (i.e. StyledTextPrinter and theme drawing). Without Direct2D/DirectWrite Xojo could not completely support HiDPI effectively. The main issue was text rendering in the code editor and swithing to GDI+ text rendering was deemed too slow. Other benefits of Direct2D/DirectWrite include: hardware acceleration, low CPU usage, improved text rendering and scaling.

Consequences of the transition

While new technology solves many immediate and future problems, it can also introduce some growing pains. For example, Microsoft didn’t introduce a printing API for Direct2D until Windows 8 (which was thankfully backported to Windows 7 via a Platform Update). This printing API has limited Xojo’s resolution setting among other things. Also, even though Direct2D can interoperate with GDI, this is not without some effort as Plugin developers have come to realize, especially when it comes to printing. For example, StyledTextPrinter is currently using an OS API that still takes a GDI graphics context (good luck getting Microsoft to update this control’s API) which now renders output as a scaled picture with how interoperating works. Other differences in rendering may be noticeable but these are likely just a difference in the graphics rendering APIs. While some consequences may be solved as time/features permit, some may be here to stay. We’ve fully embraced Direct2D/DirectWrite as our new graphics rendering engine and hope you will too.

Additional resources

While our framework attempts to guard one from having to learn about the underlying technology, it is still beneficial to understand why, at times, we need to make these changes. With that in mind, here’s some additional resources for those curious to learn more:

Windows 7: Introducing Direct2D and DirectWrite

GDI/GDI+