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

Although Xojo for Android does not yet have full dark mode support, things continue to head in that direction. Previously your app would adjust its UI for light/dark if the Support Dark Mode property was turned on in the Android Build Settings. Starting in Xojo 2023r3, Color.TextColor and Color.FillColor also adjust their values when run in light mode or dark mode, making it easier for your custom drawing to also adapt.

MobileTextField gets a couple new additions. The ReturnPressed event is now called when, as the name suggests, return is pressed. The AllowSpellChecking property is now also available for MobileTextField and MobileTextArea.

In the Shared Build Settings Inspector there is now a Destination property as there is with other platforms.

Many Android devices have physical back buttons and all let you turn on global software controls that have a back button, but sometimes you want to have the back button clearly shown on the navigation toolbar. With Xojo 2023r3, the new HasBackButton property of MobileScreen can show a back button on the navigation toolbar.

To make it easier to write code that is applicable to both iOS and Android, but not other platforms, there is a new TargetMobile constant available for conditional compilation.

MobilePopupMenu is an all-new control for Android that makes it possible to simplify some of your user interfaces. It works similarly to a PopupMenu on Desktop or Web: when the user taps this control a list of items appears and they can choose one.

On the Advanced tab of the Android Build Settings there is a new Manifest section with a Permissions property. Here you can specify the names of Android permission constants that are needed by Declares or libraries. They are added to the AndroidManifest.xml file when the app is run/built.

MobileHTMLViewer got several enhancements. It now has various processing events, including: DocumentBegin, DocumentComplete, CancelLoad, Error, NewWindow, DocumentProgressChanged and TitleChanged.

And there is now support for running JavaScript using the ExecuteJavaScript method along with the JavaScriptResult and JavaScriptRequest events. ExecuteJavaScript is asynchronous and results appear in the JavaScriptResult event. To call the JavaScriptRequest event, use xojo.execute() in the JavaScript code. A method name and up to 5 parameters can be passed back to Xojo. Learn more in the Xojo Programming Documentation.

The last thing I want to highlight is the new Kotlin Declare. For advanced users, this adds the ability to create Android declares that can pass untouched calls via Alias (with the exception of required type/object handling) to the Kotlin compilation step. This is done by specifying Lib “Kotlin” or adding “:Kotlin” to the end of Lib. Here are a couple examples of what this can look like:

Declare Function AndroidVersion Lib "Kotlin" Alias "android.os.Build.VERSION.RELEASE" As CString

Declare Sub findAllAsync Lib "Object:ctrl:MobileHTMLViewer:Kotlin" Alias "findAllAsync(myfind.toString())" (myFind As CString)

Of course there were many bug fixes as well. Be sure to check out the full release notes for all the details.

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

To create an Android library you will need to use Android Studio, which you should already have installed as its compiler toolchain and SDK are required by Xojo.

Create a New Android project (File->New->New Project), choosing “No Activity” from the Phone and Tablet section.

You should be sure to choose Kotlin as the language and the Minimum SDK should be 26 to match what Xojo uses. For this example, I’ve named the project “LibraryTest”.

In this project, add a module (File->New->New Module), choosing the “Android Library” template. Here you can name your library, choose the language, etc. Again, stick with Kotlin.

I’m naming the library “utility” so that it can contain a random collection of things.

In the Android Studio navigator, expand the utility library and then the java folder. Yes, it is weird that Kotlin code is in a Java folder, but a lot about Android Studio is weird to me.

Right-click on “com.example.utility” and select New->Kotlin Class/File. In the selector, choose “Class” and type the name of the class as “regex” and press return. In this class will be a method to do some simple regex pattern matching.

This creates an empty class:

package com.example.utility
class regex {

}

Currently Xojo can only talk to methods in the companion class. These methods are similar to Shared methods in Xojo and work without creating a specific class instance.

In the class, add the companion object so that it looks like this:

package com.example.utility

class regex {

    companion object {

    }

}

Inside the companion object, add a method that will do simple regex pattern matching. Your code now looks like this:

package com.example.utility

class regex {

    companion object {

        fun regexmatch(regex: String, text: String): Boolean {

            // Use the regex pattern
            val pattern = Regex(regex)

            // Returns true if it matches, false if it does not.
            return pattern.matches(text)
        }

    }

}

The last step is to change the Kotlin version to match the version Xojo uses. In the Android Studio navigator, open Gradle Scripts and double-click “build.gradle (Project: LibraryTest)” to open it.

Change the last line with the kotlin.android version from whatever is there to “1.6.20”:

// Top-level build file where you can add configuration options common to all sub-projects/modules.

plugins {
    id 'com.android.application' version '8.0.2' apply false
    id 'com.android.library' version '8.0.2' apply false
    id 'org.jetbrains.kotlin.android' version '1.6.20' apply false
}

Note: You may be prompted to do a Gradle sync after making this change. Go ahead and do the sync if prompted.

The last thing to do in Android Studio is to build the library. From the Build menu, choose “Select Build Variant”. In the Build Variants panel that appears, click on the Active Build Variant value for the utility row and change it from debug to release.

Select Build->Rebuild Project to build the library file that Xojo will use.

In your file system, go to your project’s location and fine the aar file, which is located here: LibraryTest/utility/build/outputs/aar/utility-release.aar Make a note of this as we will be using it with Xojo in a moment.

Speaking of Xojo, create a new Xojo Android project and name it LibraryTest. Add a button and a table like so:

In the button’s pressed event, write the Declare statements to call the regexmatch method in the library, passing it a regex pattern and a string to test. Here is the code, which tests three strings and outputs the result to the table:

Declare Function regexmatch Lib "com.example.utility.regex" (pattern As CString, value As CString) As Boolean

// Look for g, followed by any number of "ee" pairs and ending with ks
Var pattern As String = "g([ee]+)ks?"
Var result As Boolean
Var values() As String = Array("geeks", "geeeeeeeeeeks", "geeksforgeeks")

For Each v As String In values
  result = regexmatch(pattern, v)
  Table1.AddRow(v, result.ToString)
Next

// From: https://www.geeksforgeeks.org/kotlin-regular-expression/

The important thing to note in this code is the use of CString in place of String, a requirement when working with a Declare even if it doesn’t directly apply to Android.

Also note that you need to provide the full path to the class. You have to use “com.example.utility.regex”, not just “regex”.

The next step is to add the Library to the Xojo project. Select Android in the Build Settings and add a Copy Files Build Step (Insert->Build Step->Copy Files).

Expand Android and click on CopyFiles1. Rename it to LibCopy and drag it so that it is before the Build entry. Change the Destination to “Framework Folder”.

Add the library that we built with Android Studio to this LibCopy step. Click “+” in the command bar and locate utility-release.aar.

Note: If you still have Android Studio open at this point, you should close it, otherwise it will lock debugger access and prevent the Xojo app from starting.

Pro Tip: You can keep Android Studio open and run from Xojo by choosing this preference setting: Build, Execution, Deployment -> Debugger -> Use existing manually managed server. You’ll want to set it back to “Automatically start and manage the server” if you use Android Studio for anything else. Constantly flipping that setting is common when working with Android libraries.

Run the project. If you did everything correctly, it should launch on your device or emulator. Click the button to see the output which should look like this:

With libraries you can add your own extensions to Xojo’s Android support. You are limited to simple types at the moment, but that still opens up a lot of capabilities. This capability will continue to be expanded through the Android beta.

Feel free to share any Kotlin libraries you create in the Android topic of the forum.

Download this Example RegEx Library

Here is another simple Library you can download and examine.

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.