In The Beginning

Threads have been a part of of the Xojo language for a long time, and by now experienced users know the basics: subclass a Thread, fill in the Run event, then call Start. The code in Run will execute independently from the rest of your code leaving your app responsive while it does work in the background.

Mostly.

See, until now, a Thread was only “cooperative”, meaning it ran alongside your main code with the framework deciding when to switch between them and how long each should execute. While the main code was running, the Thread code was paused, and while the Thread was running, the main code was paused.

Think of it like standing before two devices that perform different functions when cranked, but only having one crank available. You run the first machine for a bit, then the other, then back to the first, until they are done. And you do it really, really fast.

This worked pretty well when your goal was, say, to keep your user interface responsive. You could spin long-running code into a Thread, then present the results once it finished.

But it was inadequate if your objective was to speed up some intense process, or the code in your Thread did not present logical places to yield time back to your main code. In the former scenario, you were better off not using a Thread, or perhaps using Worker (a severely limited earlier attempt at allowing simultaneous processing), while in the latter you would have to manually yield back processing time, leading to even slower operation.

In The Now

Cooperative threads are fine for many tasks, but when you need something that truly runs independently within your app, a “preemptive” thread is required.

A preemptive thread spins off onto another core in your machine, which probably has at least four, and runs there entirely isolated from other threads. It’s like launching a separate, mini-app that you can share information with.

The limitations that apply to cooperative threads drop away. Since it runs on a different core, it cannot slow down or interfere with your main code, and will run as fast as its core will allow.

Challenging Times

This sounds almost too good to be true, but it’s not without its challenges. While cooperative threads were rather easy to work with, preemptive threads require an extra layer of thought and awareness for Xojo users.

When a cooperative thread’s code is running, you know nothing else is, so you don’t have to worry about, say, updating a Dictionary or removing an element from an array. But with preemptive threads, code runs simultaneously with other code so you cannot just update that Dictionary if there is a chance that the main code, or another preemptive thread, might be doing it too.

Consider this example.

// In our thread
If MyArray.Count = 0 And FinishUp Then
  Exit
Else
  Process MyArray.Pop
End If

//////////////////////////////

// In the main code
FinishUp = True
MyArray.Add 1

You might think the thread is going to process the last element and then exit its loop because FinishUp was set to True, but with preemptive threads we have to be aware of race conditions where the order of actions is unpredictable. Here, the main code could set FinishUp to True, and the thread could see that MyArray was empty and exit before the main code could add the last element. Conditions can change at literally any instant, even in the middle of a single line of code.

Fortunately, there are ways to protect against this and you must use them to ensure orderly operation and avoid surprises.

Know Your Type

The first step is creating a preemptive thread, and Xojo’s implementation is pretty straightforward. Rather than introducing a unique class, you can continue to work with the existing Thread by setting its new Type property to Thread.Types.Preemptive. The Type can be set when instantiating the Thread or from within its running code. You can even switch types at will, although once running, the Type can only be changed from within the Thread.

Example:

// A subclass of Thread called PThread

MyThread = New PThread
PThread.Type = Thread.Types.Preemptive
PThread.Start

Or within the Run event, you could do this:

Me.Type = Thread.Types.Preemptive

You can also set Type through the Inspector after dragging a Thread to a window.

Protect Yourself

Now that you have a preemptive thread ready to go, you have to think about how to protect common resources. Xojo has done a good job of making a lot of the framework safe, but that just means your app shouldn’t crash if, say, the Thread tries to manipulate a variable at the same time as other code. It’s up to you to make sure one area of your app doesn’t clobber the changes made by another.

Consider this code that maintains a Dictionary of Integer arrays.

// Thread code
Var arr() As Integer

If MyDictionary.HasKey(x) Then
  arr = MyDictionary.Value(x)
Else
  MyDictionary.Value(x) = arr
End If

arr.Add 1

//////////////////////////////

// Main code
If Not MyDictionary.HasKey(x) Then
  Var arr() As Integer
  MyDictionary.Value(x) = arr
End If

Run this long enough and you’re going to wonder why some data got lost. Why? Because both the Thread and main code might be checking for the key at the exact same instant and filling it in when it’s not found. If the Thread does it first, the main code will almost instantly replace it with an empty array.

Instead, you should use a Semaphore or CriticalSection to make sure code is protected.

You’d first instantiate one of these in a common property like a Window or Module. (I’m using Semaphore here, but it works the same for CriticalSection.)

MySemaphore = New Semaphore
MySemaphore.Type = Thread.Types.Preemptive

Notice the new Type property? It must match the one in Thread and can be used between the main code and a Thread or between same-typed threads. (This is one of the limitations of Xojo’s implementation: you cannot share a Semaphore or CriticalSection between preemptive and cooperative threads.)

The example can be updated like this:

// Thread code
Var arr() As Integer

MySemaphore.Signal

If MyDictionary.HasKey(x) Then
  arr = MyDictionary.Value(x)
Else
  MyDictionary.Value(x) = arr
End If

MySemaphore.Release

arr.Add 1

//////////////////////////////

// Main code
MySemaphore.Signal

If Not MyDictionary.HasKey(x) Then
  Var arr() As Integer
  MyDictionary.Value(x) = arr
End If

MySemaphore.Release

This will force either the main code or Thread to wait for the other to complete before continuing, ensuring proper order and avoiding the race condition.

Limitations

Using preemptive threads comes with certain restrictions. The biggest one is the aforementioned inability to share a Semaphore or CriticalSection with a cooperative thread. The other is the same as in a cooperative thread: you cannot update a user interface component directly instead relying on the UserInterfaceUpdate mechanism (more on that below).

If you are setting up multiple threads to work on different parts of some object, that may crash hard depending on the type of object. For example, writing to the same file or different parts of a MemoryBlock is fine, but updating a Picture may not be. In those cases, you will have to get creative.

What’s It Good For?

Choosing preemptive threads over cooperative means that you either have some code that needs to truly run in the background that would otherwise interfere with you user interface, or you have some large task that can be logically processed in parts.

Window Service

In the former case, the easiest technique might be to drag a Thread to your window, set its Type, and implement the Run event. It can be started from within the window either through a manual process like a pressing a button, or automatically when the window opens.

Just like with a cooperative thread, you can send data back to your window using the AddUserInterfaceUpdate method and implementing the UserInterfaceUpdate event.

Splitting It Up

If your task involves something that can be split up into logical chunks, I encourage you to look at my ThreadPool module, accessible through the Xojo Examples or my GitHub page. (The latter has a README with more details.)

The ideal usage for ThreadPool is when you have some data that can be processed in sections. For example, suppose you wanted to count the vowels in a large file. You could subclass ThreadPool and implement its Process event to count one block. You would then send the file into your subclass in chunks of, say, 256k each and gather the results.

The benefit of ThreadPool, among other things, is that it will handle the coordination for you so the dangers of using preemptive threads are minimized. You still have to consider how to send your results back to your main code safely, perhaps using Semaphore/CriticalSection or the AddUserInterfaceUpdate method, but each block can be considered independently of the others.

(A big thanks to MVP Anthony Cyphers for writing the example included with Xojo.)

Juggling Chainsaws

The power of preemptive threads is clear, but the potential pitfalls can be serious. Unless you’re very careful, you can easily create bugs that may not be readily apparent, and may take hours or even days to track down. (I say this from unfortunate experience.) Unless you have a compelling reason to take on that challenge, don’t bother.

What I’m trying to say is, if a cooperate thread does the job adequately, there is no need to introduce the headache that preemptive threads can bring.

But if you do have a legitimate need, like a long-running process that needs to run quickly without blocking your UI, go for it, just be careful.

In any case, it’s great that we finally have that option.

Kem Tekinay is a Mac consultant and programmer who has been using Xojo since its first release to create custom solutions for clients. He is the author of the popular utilities TFTP Client and RegExRX (both written with Xojo) and lives in Connecticut with his wife Lisa, and their cat.

Need More Information? Read more about preemptive threads in the Xojo Documentation and Blog. Or read about Semaphore and CriticalSection, also on the Xojo Blog.

A Quick Reminder About What Bootstrap Is

As I will be mentioning it during this post, let me take a moment to remind readers what Bootstrap is, and what are we using it for at Xojo.

Bootstrap is the library we use for the visual part of web applications made with Xojo. You can think about it as Gtk on Linux, or UIKit on iOS.

While there is a vast amount of alternative libraries, it’s been probably the most popular framework for the last decade. You can check the Bootstrap website for more information.

ColorGroup Named Colors

Until this release, the Named option when configuring a ColorGroup was not available on web projects. 2024r3 brings the ability to choose from the Web Basic colors, Web Extended colors and, what I find more interesting, Bootstrap colors, which also support dark mode out of the box.

As you can expect, if you drop a custom Bootstrap 5.3 theme with another set of colors, the IDE will automatically update in order to preview them.

Using Named Colors by Code

When a dynamic need arises, it is also possible to use Bootstrap Named colors programmatically, if you find it easier. Here is an example:

Var colorName As String

If paymentCardIsValid Then
  colorName = "success"
Else
  colorName = "danger"
End If

Rectangle1.BackgroundColor = ColorGroup.NamedColor(colorName)

Or in a WebCanvas.Paint event:

Var colorName As String = If(paymentCardIsValid, "success", "danger")
g.DrawingColor = ColorGroup.NamedColor(colorName)
g.FillRectangle(0, 0, g.Width, g.Height)

You can check the list of available colors in the Color section of the official Bootstrap documentation. Basic and Extended Web Colors will work as well.

Using Bootstrap CSS Classes

Bootstrap comes with a set of utility CSS classes for a variety of visual things. You probably won’t need them all, as the Xojo IDE will get you there in most of the cases, and we work hard improving the IDE to make it easier, release by release.

That said, if you are an advanced user, and you have previous experience working with Bootstrap, you may find it useful to add CSS classes directly from the Inspector.

Go to the Advanced tab, add some Bootstrap CSS classes, separated by spaces… and voilà!

Here is a demo:

We have included a new example, called “Applying Bootstrap CSS classes to controls”, that you can find under Platforms > Web. Please give it a try.

CSS Classes are not limited to Bootstrap, if you have added styles in the HTML Header section, you can use them as well.

You can also add and remove them using the new CSSClasses property, which is available in every WebUIControl subclass.

WebRectangle Got Some Love

You won’t need to setup the border color, border thickness or the corner size, for WebRectangle, in the Opening event anymore.

When designing web applications, I found myself using a lot of WebRectangle controls and, by default, they have a rounded border.

The side-effect is subtle, but now that you can control the border radius directly from the Inspector, the IDE preview will be closer to how it will look in the browser. And you are going to avoid writing a few lines of code!

In addition, some Bootstrap themes define a different Corner Size. Setting this property to “-1” will honor that Bootstrap theme’s default border radius.

Conclusion

As always, the release comes with much more than I can tell you about in one blog post. With over 30 Bug fixes and 9 Feature Requests implemented in the Web target alone, make sure to take a look at the Xojo 2024r3 Release Notes to see the whole picture.

Happy coding!

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

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Threading Models

Cooperative Threads: This is the threading model that Xojo has traditionally supported and continues to offer. In this model, threads must voluntarily yield control at specific points that we define. This ensures that most operations in Xojo code are thread-safe, as we manage access to MemoryBlocks, Arrays, etc. However, this approach can lead to inefficiencies if a thread fails to yield, potentially blocking UI, and because only one thread runs at a time, it doesn’t fully utilize multiple cores or truly run in parallel.

Preemptive Threads: Introduced in Xojo 2024r3, this new thread type allows threads to be interrupted at any point, enhancing responsiveness and fully utilizing multiple cores. While this model provides significant performance improvements, it also introduces new challenges. Because threads can be interrupted at any time, you’ll need to be more diligent about locking resources, such as MemoryBlocks and Arrays, to avoid potential race conditions.

Using Preemptive Threads

We’ve added a new Thread.Type property that allows you to switch your threads to the new preemptive thread model, here’s how you can start one up:

Thread1.Type = Threads.Types.Preemptive
Thread1.Start

You can set this property either before starting your thread or while the thread is running. However, if changing it while the thread is active, it must be done safely from within the running thread itself, and not externally.

Event Window1.Opening
  // Start the thread and setup the type in the Run event instead
  Thread1.Start
End Event

Sub Thread1.Run
  Me.Type = Threads.Types.Preemptive
  // Run a very long process preemptively.
  newMemBlock = memBlock.Compress
  
  Me.Type = Threads.Types.Cooperative
  // Switching to cooperative mode and modifying a shared array safely.
  mySharedArray.Add("New item")
End Sub

Concurrency and Synchronization

As mentioned earlier, cooperative threads avoid many of the issues that arise with preemptive threads, since we control when thread switching occurs. With preemptive threads, however, you can no longer safely modify things, like shared arrays, the same way you could before with cooperative threads. To manage this, you’ll need to use tools like CriticalSections and Semaphores more frequently to protect your shared resources.

The challenge lies in efficiently supporting both threading models while enabling the main thread to synchronize with either type. To address this, we’ve added a new Type property to CriticalSection and Semaphores, which must match the thread type you’re using to protect shared resources.

// Imagine the main thread and two additional threads all trying to access a Dictionary simultaneously.
Sub RunTest
  Thread1.Type = Thread.Types.Preemptive
  Thread2.Type = Thread.Types.Preemptive

  CSLock = New CriticalSection
  // Since we are using this CriticalSection in preemptive threads,
  // the synchronization type must be compatible.
  CSLock.Type = Thread1.Type

  Thread1.Start
  Thread2.Start

  Do
    CSLock.Enter
    MyDictionary.RemoveAll
    CSLock.Leave
  Loop
End Sub

Sub Thread1.Run
  Do
    CSLock.Enter
    MyDictionary.Value("Random1") = Rnd
    CSLock.Leave
  Loop
End Sub

Sub Thread2.Run
  Do
    CSLock.Enter
    MyDictionary.Value("Random2") = Rnd
    CSLock.Leave
  Loop
End Sub

What things are thread-safe?

We’ve updated our framework to safeguard areas that were previously not preemptive thread-safe. For the most part, our entire framework is now safe for concurrent use with preemptive threads, with a few exceptions like XojoScript and Runtime.IterateObjects. When sharing resources such as MemoryBlocks, Dictionaries, or Arrays among threads, you may need to use CriticalSections or Semaphores to ensure safe access. However, if you’re only reading from these resources without modifying them, synchronization is not required. You’ll be happy to know that calling Thread.AddUserInterfaceUpdate from a preemptive thread is also safe.

Performance Considerations

With the ability to switch your threads to preemptive, there are some performance factors to consider. While running 100 threads at once might seem appealing, it often leads to over-utilizing your system’s resources. For optimal efficiency, it’s best to limit the number of threads to match the number of available cores. To assist with this, we’ve introduced the new System.CoreCount, which helps you determine the number of cores on your system.

While Xojo’s framework doesn’t shield you from every potential issue, we do handle synchronization for key operations like object creation and destruction. However, you may notice these actions are slower in preemptive threads due to the extra synchronization required.

Usage and Examples

There’s no question that preemptive threads offer significant advantages, and when used correctly, they can greatly enhance your app’s performance. Check out our threading example projects included with the 2024r3 release to see preemptive threads in action and enjoy weaving these new threads into your future apps!

A special thanks to our MVPs for their invaluable help in refining and testing this new feature! Be sure to check out the new ThreadPool example for some practical, real-world use cases and read MVP Kem Tekinay’s blog post Preemptive Threads Are Here and They Are …. Pretty Good.

Need More Information? Read more about preemptive threads in the Xojo Documentation and Blog. Or read about Semaphore and CriticalSection.

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

Layout Editor

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

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

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

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

Default Screen

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

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

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

Design Considerations

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

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

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

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

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

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

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

What about Chromebook?

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

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

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

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

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

Eddie’s Electronics Example Project

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

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

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

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

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

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

What is SOUNDEX?

SOUNDEX is a core function in SQLite that encodes a string into a 4-byte sequence, enabling indexing based on pronunciation. While the technical details of the algorithm are available on Wikipedia, the gist is that SOUNDEX(“Smith”) will match SOUNDEX(“Smythe”), making it useful for large searches to identify different spellings of the same term.

How is it used?

For the curious, you can see how words are indexed by simply invoking a select on a SOUNDEX term:

Var db As New SQLiteDatabase
db.Connect

Var rs As RowSet
rs = db.SelectSQL("SELECT SOUNDEX('Smith')")
Var smith As String = rs.ColumnAt(0).StringValue
rs = db.SelectSQL("SELECT SOUNDEX('Smythe')")
Var smythe As String = rs.ColumnAt(0).StringValue

Running this you’ll notice that ‘Smith’ and ‘Smythe’ both return the same SOUNDEX 4-byte sequence of “S530” — Here’s a quick breakdown of how this was generated:

1. First Letter (S): The first letter of the name stays the same, so “S” from the name “Smith” or “Smythe” becomes the first character in the code.
2. Numbers (530): The remaining characters in the code represent the sounds of the next letters in the name. Each number is based on a group of similar-sounding consonants:
   • 5 = “M” (because M sounds like “M” in “Smith” or “Smythe”)
   • 3 = “T” (because T sounds like “T” in “Smith” or “Smythe”)
   • 0 = No sound match or a vowel, so it acts as a filler to complete the 4-character code.

Practical Use Case

With a better understanding of the algorithm, we can put it to practical use by searching our database for names that sound similar to “Smith.”

db.ExecuteSQL("CREATE TABLE contacts(id INTEGER PRIMARY KEY, name TEXT)")
db.ExecuteSQL("INSERT INTO contacts (name) VALUES ('Smith'), ('Smythe'), ('Simith'), ('John')")

rs = db.SelectSQL("SELECT name FROM contacts WHERE SOUNDEX(name) = SOUNDEX('Smith')")

// Expected to find 3 names: Smith, Smythe, and Simith
Var namesFound As Integer = rs.RowCount

The Fuzzy Conclusion

Because the SOUNDEX algorithm is designed around English pronunciation patterns, it may not work as well for languages with different sound structures or alphabets, so results may vary depending on the language. It’s also worth noting that this feature is available for all targets, except Android at this time.

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

Getting the Image Metadata

In order to get the metadata from a given image, first retrieve a valid instance from the Picture Class using MobileImagePicker, select Photos or Camera as the image source.

Once we get the Picture instance, for example as the received parameter in the Selected event from the ImagePicker instance, we only need to access its Metadata property. The property will return a Dictionary instance, so we can iterate its entries or convert it to a JSONItem instance for simplicity if all you want to do is store the information. For example, we can use the following fragment of code in the Selected event of the ImagePicker instance:

Var js As JSONItem
Try
  js = New JSONItem(pic.Metadata)
  MessageBox(js.ToString)
Catch e As JSONException

End Try

Assuming that “pic” is the name of the received parameter that points to the user selected (or captured) image, the previous fragment of code will show a dialog with the image metadata.

Getting the Image Location… and Putting it On the Map!

An interesting action could be reading the location data of the selected image and adding an entry on a MobileMapViewer instance. So, for example, again in the Selected event of an ImagePicker instance, we could add the following snippet of code:

If pic <> Nil Then
  ImageViewer.Image = pic
  
  // The metadata is retrieved as a Dictionary, so let's get the
  // metadata from the selected picture
  metadata  = pic.Metadata
  
  If metadata <> Nil Then
    Var jlocation As Dictionary = metadata.Lookup("Location", Nil)
    
    // Getting the Location information (also as Dictionary)
    If jlocation <> Nil Then
      
      // And assigning the Latitude and Longitude
      // values to the properties
      latitude  = jlocation.Value("Latitude").DoubleValue
      longitude = jlocation.Value("Longitude").DoubleValue
      
      // Then, we will show the Picture location on the Map
      Timer.CallLater(100, AddressOf Showlocation)
    End If
    
  End If
  
End If

Latitude and Longitude are Double type properties that have been added to the Screen containing the ImagePicker instance, also added is an ImageViewer instance responsible for displaying the selected image preview, and a MapViewer instance on which the “pin” corresponding to the location of the image will be added.

As you can see, the shared method CallLater of the Timer class is used to invoke the ShowLocation method. This method will be responsible for displaying the actual pin on the map:

Private Sub Showlocation()
  // Let's create a new Location instance from the stored
  // latitude and longitude values in order to add it
  // to the Mapviewer…
  
  Var maplocation As New MapLocation(latitude, longitude)
  MapViewer1.AddLocation(maplocation)
  
  // …and let's make sure the metadata is updated
  // to the viewed image
  ImageViewer.Image.Metadata = metadata
End Sub

The following screenshot shows the outcome of executing the previous code:

Of course, you’ll need to enable the Maps entitlement in the Build Settings > iOS > Capabilities inspector.

Setting the Location in a Picture

Just as we can get the location out of an image, we can also modify it… or set a location to those photographs that we get through the ImagePicker using the Camera source. Assigning a location is very simple:

• Add an instance of MobileLocation to the project (for example the screen where we manage image capture).
• Add the Latitude and Longitude properties of type Double as two new properties on the same screen.
• In the LocationChanged event of the MobilLocation instance assign the values received in the Latitude and Longitude parameters to the properties created previously:

Self.Latitude = Latitude
Self.Longitude = Longitude

• Then, in the Selected event of the ImagePicker instance, use the following snippet of code:

Var d As New Dictionary
d.Value("Latitude") = Self.Latitude
d.Value("Longitude") = Self.Longitude

Var Location As New Dictionary
Location.Value("Location") = d

pic.Metadata = Location

Saving Pictures to Photos

Until now, MobileSharingPanel was probably the go-to option when it came to saving any of the images generated in your iOS Xojo app or images captured with the camera using the ImagePicker. Starting with Xojo 2024r3, you can also use the SaveToPhotos method of the Picture class, which will take care of saving the image while preserving the associated metadata.

So, for example, you will only have to add the following line of code at the end of the previous block so that the captured image is saved with the location:

pic.SaveToPhotos(Picture.Formats.PNG)

However, when using this method on images in your iOS app, make sure to enable the Photos Access capability in the Build Settings > iOS > Capabilities Inspector Panel.

Wrapping-Up

As you have seen, it’s now really easy to get metadata from Picture instances in your Xojo iOS apps, as well as leverage Location information and assign location information to any of existing or new images. Plus, you no longer need to resort to MobileSharingPanel if all you want is your iOS app to save images to the Photos app album on the iOS device.

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 post describes the things you can do with Declares and Libraries with Android projects.

Declare Integer Types

The size-specific Integer types are now precise when used with Declares. The mappings are as follows:

When mapping to Android API functions or Library functions, be sure to use the correct Xojo type that matches what is expected on Android. By far you will use Int32 and Integer.

If you previously created Declares, you will likely need to change usage of Integer to Int32 as the mapping for that have changed compared to prior versions.

Nullable Types

Xojo object variables (also properties, parameters and return values) can be Nil. With Kotlin, the default is that these things cannot be null (the equivalent of Nil). To ensure that you don’t get compile errors with your parameters, declare them as nullable in Kotlin by appending the “?” to the end of the type name.

Application Context

Many Android APIs require the application context. This is not available in a Library so it has to be supplied by the app itself. There is a property for this:

MobileApplication.AndroidContextHandle As Ptr

You can pass this value to a function on the Library that then either saves it or uses it directly.

Using Ptr

Xojo uses the Ptr type to interface with Declares, however Kotlin does not have a Ptr type. Instead the Any type is used with Kotlin. This means that if you are passing something that is a Ptr to Kotlin (such as the app context above), your library function declaration should use “Any?” as the type of the parameter.

In your function, cast the parameter to the actual type you want. The same rule applies to return values. If the return value in the Declare is a Ptr, then in Kotlin the function declaration should be “Any?”.

You can also use Ptr with API calls to save object references as described below.

Library Permissions

Depending on the API you are using, you may need to add permissions to the app manifest.xml for the Library. These permissions also need to be applied to the main app. This can be done using the Advanced tab of the Android Build Settings. There you’ll find the Permissions property in the Inspector where you can add one Permission per line.

Previous versions let you separate permissions by spaces or commas. Going forward, each permission must be on its own line. Empty lines are ignored.

There you can add the permission constants that are required by your Library. In addition, you can follow the constant with additional attributes and they will also be applied to the app’s manifest file.

For example, to include the android:maxSdkVersion attribute with the BLUETOOTH permission:

android.permission.BLUETOOTH android:maxSdkVersion="30"

Library Dependencies

Similarly to permissions, your Library may make use of additional dependencies, which could even be other Libraries. These are added to the build.gradle file for the Library, but also need to be included in the main app.

You can add these dependencies using the Dependencies property on the Advanced Android Build Settings.

Creating Objects

Previous versions of Xojo only let you call Companion (essentially shared) methods on Library classes. Now you can also work with class instances and call instance methods. This gives you even better control and ability to interface with Android APIs.

To create an object, your Library class should have a factory method on the Companion that returns a new instance. It is clearest to use create() as this method name.

In Xojo you create a Declare to this create() method and call it, saving the result in a Ptr.

Declare Function create Lib "com.example.utility.counter" () As Ptr
Var counter As Ptr = create

Instead of using a shared factory method, you can also call the Class constructor using this syntax:

Declare Function counter Lib "com.example.utility.counter" () As Ptr

Because the function name has the same name as the class itself, this will call the constructor of the class.

When you want to call a method on the instance, you pass the instance as a Ptr. First, Declare to the method adding “.instance” to the library location to indicate you are calling a class instance.

Declare Function increment Lib "com.example.utility.counter.instance" (ref As Ptr) As Integer

Then you can call the method and save its value.

Var count As Integer = increment(counter)

The reference as the Ptr must be the first parameter passed in the Declare. Follow it with other parameters as usual.

You can also call instance methods directly in the Android API in this manner.

Method Callbacks

There are Android APIs that use callbacks to methods that you provide. In Xojo these methods are Delegates and are methods that you supply using AddressOf. It is very important that the signature of this method exactly matches what the callback expects which means you’ll be limited to just the Boolean and Ptr types.

If you want to use an API that uses its own callbacks, you’ll be better served by creating a Library and having the API do the callback to your own Library methods, which you can then call back to your Xojo methods.

You can pass the reference to the Xojo method using AddressOf like this:

Var cb As Ptr = AddressOf TestCallback
Declare Sub xojocallback Lib "com.example.utility.callback" (cb As Ptr)
xojocallback(cb)

The Xojo method can only use parameter types of Boolean and Ptr. It looks like this:

Public Sub TestCallback(b As Boolean, i As Ptr, s As Ptr)

In the Kotlin library you have to cast the incoming parameter to a function reference. This is a two-step process where you verify the function has the correct number of parameters and then you cast it to the specific parameter types. Sample code:

if (cb is Function3<*, *, *, *>) {
    try {
         (cb as Function3<Boolean, Long, String, Unit>).invoke(true, 42, "Hello")
         println("Sent callback to Xojo")
    } catch (e: ClassCastException) {
         println("Casting failed: ${e.message}")
    }
}

The “Function3” indicates a function with 3 parameters (the last “*” indicates the return type), but you can change that as needed using Function1, Function2, etc. You can pass anything back through a Ptr type, but the Xojo code has to convert them using Ptr methods so you should not change the types of the values you send back to be different than what your Xojo code expects.

Object Declares

Object Declares are not new, but for completeness are described here. Essentially an Object Declare uses special syntax to Declare to a UI control.

The typical way to use an Object Declare is by adding an Extends method to a Module. For example, an extension method to allow MobileButton to change its colors could look like this:

SetBackColor(Extends ctrl As MobileButton, c As Color)

The Object Declare looks like this:

Declare Sub setBackgroundColor Lib "Object:ctrl:MobileButton" (myColor As Int32)
setBackgroundColor(c.ToInteger)

Breaking this down, we’re calling the setBackgroundColor function. The Lib denotes this new type of Object declare: an Object, separated by a colon, the Xojo name of the object (in this case, our “ctrl” parameter), followed by another colon, and the Xojo type of the object.

Kotlin Declares

You can use the Android-specific “Kotlin” Declare designation to indicates that what is specified in the Alias section of the Declare should be used as is. This is particularly helpful when you want to cast Ptr values to a specific type for use with OS APIs.

This code gets a ColorStateList object for a Xojo Color value:

Var c As Color = Color.Blue

Declare Function valueOf Lib "android.content.res.ColorStateList:Kotlin" Alias _
"android.content.res.ColorStateList.valueOf(android.graphics.Color.argb(alpha.toInt(), r.toInt(), g.toInt(), b.toInt()))" _
(alpha As Int32, r As Int32, g As Int32, b As Int32) As Ptr

Var csl As Ptr = valueOf(255 - c.Alpha, c.Red, c.Green, c.Blue)

This code can then be used to call setStrokeColor on a MobileButton:

Declare Sub import Lib "android.content.res.ColorStateList:Import" // Imports the ColorStateList class

Declare Sub setStrokeColor Lib "Object:ctrl:MobileDateTimePicker:Kotlin" Alias "setStrokeColor(strokecolor as ColorStateList)" (strokeColor As Ptr)
setStrokeColor(csl)

As you can see, in the Alias is the Kotlin method call that casts the incoming Ptr value to a ColorStateList.

Import

Note the “import” declare in the code snippet above. This is also specific to Android. This Declare indicates that a specific class should be imported so that it can be used for casting purposes. If you left off that import, then the cast to ColorStateList would cause a compile error because ColorStateList would not be known.

You only need to import a specific class once. After you’ve done so it can be referenced by any other Declare, even ones in different methods.

The use of an import Declare is optional and is meant to simply the Kotlin method call code in the Alias. Instead of using import you can specify the full class path in the cast like this:

Declare Sub setStrokeColor Lib "Object:ctrl:MobileDateTimePicker:Kotlin" Alias "setStrokeColor(strokecolor as android.content.res.ColorStateList)" (strokeColor As Ptr)
setStrokeColor(csl)

Handles

Many classes in the framework now have Handle properties (or methods) which you can use with various Declare techniques described above. These include: FolderItem, Font, GraphicsPath, Locale, TimeZone, Graphics, Picture. In addition, the mobile controls have Handle properties that can serve as an alternative for an Object Declare.

Sample Project

You can download the sample project that demonstrates a library and some of the concepts described above. You can use this as a template or starting point for creating your own libraries or Declares.

Sample Utility Library Project

You might also want to take a look at the Android Design Extensions open source project, which has hundreds of Declares that can enhance your Android apps.

References

• Android Libraries blog post
• Android Declares blog post

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

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Line Highlight

The first change is that the entire line containing the cursor is now highlighted. This makes it much easier to find where your cursor is on large displays and matches behavior that is common in other coding editors, such as BBEdit or Visual Studio Code. This highlight is controlled in Coding Settings:

Here is what he row highlight looks like:

Syntax Help Area

With the enhancement to show method overloads in the Syntax Help area a couple years ago, the area was changed to dynamically resize its contents depending on what is shown there. Although some liked this design there were others that felt that it was distracting to have the Syntax Help Area size change so often.

An improvement made last year altered the syntax help area behavior so that it is only updated when the mouse cursor stops moving for a moment. Because of that change, we are able to introduce the option to have a fixed-size Syntax Help Area.

In the Coding Settings, you can choose: 2, 3, 4, 5, 6 Lines or Resizable. The default is now 3 lines. If more information is shown than will fit in the Syntax Help Area, there is a scrollbar (which you can now actually use since the area won’t update with new information until you stop moving the mouse).

You should also notice improved syntax help in general. The lookup engine is now better able to infer context to show more accurate information. I’m particularly pleased that CType now shows in the Syntax Help Area because I can never remember the order of the parameters!

Standardize Format

A long-standing request (from 2010!) was to have the Standardize Format option available on the Code Editor command bar. Lots of people like their code formatted nicely and Standardize Format is a great way to do that.

Now you can easily click a button on the command bar to quickly format everything in the code editor, instead of first having to Select All and then choose a contextual menu option.

If you really like your code to be formatted automatically, don’t forget you can always turn on “Apply standardize format after ending line” in the Coding Settings.

And don’t forget that you can also create your own script to format your code any way you want. Learn more about this in Custom Code Reformatting in the docs. You might also want to try to this powerful reformatting script.

If you have other suggestions for Code Editor improvements, please be sure to create an Issue. One popular suggestion is to have the text under the cursor be highlighted throughout the code editor (see Issue #74741), which I have started to investigate. Read all about the Xojo Code Editor in the Xojo Docs.

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

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

What’s New in Xojo 2024 Release 3

We’ve been working hard to bring you the best possible cross-platform development experience, and Xojo 2024 Release 3 delivers. Here are some of the highlights:

These updates and enhancements are designed to make your development experience more efficient, productive, and enjoyable. Whether you’re building a new application or updating an existing one, Xojo 2024 Release 3 provides you with the tools and capabilities you need to succeed.

Get Started

To learn more about Xojo 2024 Release 3 and to get started with the development process, please visit the Xojo 2024r3 Release Notes. The update can be downloaded right now, from the Xojo downloads page.

What’s Next?

We’re always working on new features, updates, and enhancements to our platform. If you have any suggestions or ideas, please don’t hesitate to add them to the Xojo tracker. We’re always looking for ways to improve and expand Xojo.

Thank you for being part of the Xojo community. We’re excited to see what you’ll create with Xojo 2024r3!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube