When you create a Library in Xojo, it’s tailored to the project type you’re working in, whether that is Desktop, Web, Mobile or Console, so everything stays organized and easy to manage. The Library format was designed to support all project types simultaneously; unfortunately, the Xojo IDE was not. The good news is that there are still ways to take advantage of the flexible underlying format. Since Libraries are simply .zip files, you can change the extension to .zip and decompress them to explore their contents. Inside, you’ll find a folder named for the project type you originally created it from, making it easy to understand the structure. Here are two ways to create Libraries that support multiple project types.

Merging Libraries Manually

To manually create a multi-project-type Library, start by building a separate Library for each project type your functionality supports, then change each one’s extension to .zip and decompress it. Choose one decompressed Library to serve as the final version, and copy the project-type folders (Desktop, Web, iOS, Android or Console) from the others into it. When everything is combined, recompress the folder back into a .zip file and change the extension to .xojo_library. You now have a single Library that works across all the project types you included.

Using LibMerge

LibMerge is a utility we created to make it easier to merge Libraries.

1. Download LibMerge for Linux, macOS or Windows. It will be included in the Extras folder in the next major release.
2. Launch LibMerge and then click the Add button to select the Libraries you wish to merge or drag them into the Libraries list in the LibMerge window.
3. On the Info tab, make sure the Version, Copyright and Description values are as you want them for the merged Library. These initial values are loaded from the first Library you add to the list.
4. Click the Save As button to choose a name and location for your merged Library. That’s it!

If you choose two libraries that both already support the same project type, LibMerge will tell you and not load the second Library. Included with LibMerge is the LibMerge Library which you can use to build the merging of Libraries into your own build tools. Check out the included LibMerge API Guide for details. Here is an example:

Try
   Var merge As New LibMerger
   merge.AddLibrary(SpecialFolder.Desktop.Child("MyDesktopLibrary.xojo_library"))
   merge.AddLibrary(SpecialFolder.Desktop.Child("MyWebLibrary.xojo_library"))
   merge.SaveMergedLibrary(SpecialFolder.Desktop.Child("MergedLibrary.xojo_library"))
Catch error as UnsupportedFormatException
   System.Beep
   MessageBox(error.Message)
End Try

Whether you prefer to roll up your sleeves and merge Libraries manually or let LibMerge handle the heavy lifting, Xojo gives you the flexibility to build reusable components that work across all your project types. With a little exploration and the right tools you can streamline your workflow, reduce duplication and keep your projects cleaner and more maintainable. LibMerge makes this process fast and reliable whether you’re merging two Libraries or twenty. Read more about Libraries in the Xojo Documentation.

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

What is a Library?

A Library is a collection of pre-written, reusable code containing methods, classes and UI. Up until now, the way to distribute a Library for use with Xojo was to create a Plugin or to manually re-use project items across projects. Both have pros and cons.

Plugins are compiled and do not expose source code, but plugins cannot be created using Xojo itself and are typically created using C/C++ along with the Xojo Plugin SDK. Sharing project items is fine for internal projects or open-source projects, but less ideal for commercial libraries. They can be harder to manually add to a project and are recompiled along with the project, slowing the debug process.

With a Xojo Library, you can now create your own compiled Library using Xojo itself. This Library can contain nearly any Xojo project item and can be easily used in other Xojo projects because it is distributed as a single file.

At a high-level, you create your Library in Xojo, add your project items to it and built it into a Library package file. Other projects can then use this Library package, which gives them access to the items you included in the Library.

Creating a Library

Here is a brief overview of how you create a Xojo Library:

1. In a Desktop, Web, Console or iOS project add a Library by choosing Insert->Library.
2. Add the project items you want to the Library. Any Xojo project item is supported, except for Worker.
3. Build the project. It will build the main app (which should serve as a test app for your Library) and a separate Library package file (with extension .xojo_library).
4. You can put this Library package alongside another project (on the drive) and it will be loaded when that project is opened by Xojo. You can then use the classes, methods and UI contained in the Library within your project. If you instead put the Library in the Plugins folder, then it will be available for all projects.

This is all best demonstrated by a quick example. Go ahead and create a Desktop project and add a Library to it, which adds a Library1 project item to the Navigator. Change its name using the Inspector to LibHello.

While LibHello is selected, choose Insert->Class. This adds Class1 to it. This new class is now part of the Library. With Class1 selected, change its name to StringStuff.

You can now add whatever methods or properties you want to the class. For our example purposes here we will add a simple method that reverses a string.

Public Function ReverseString(s As String) As String
  Var newString As String
  
  For Each c As String In s.Characters
    newString = c + newString
  Next
  
  Return newString
End Function

The Library could contain many other things of course, but to keep things simple this Library will have just the single class with its single method. Here’s what it looks like in the project:

The first thing to do is to test this Library ReverseString method. Add a button to Window1 and have it call the function, verifying the result.

Var stuff As New StringStuff
Var result As String = stuff.ReverseString("Xojo")

MessageBox(result)

When you run, you can see the output:

So far this is all not much different than you would normally be doing with a Xojo project. The next step is to create the Library package for use by other projects.

In the Build Settings area, select Shared. This is where you can enter some information about the Library that can be seen by those that use it.

• In the Version field, enter “1.0”.
• In the Copyright field, enter “Acme, Inc.”
• In the Description field, enter “A Xojo Library test.”

Also in the Build Settings area, check the boxes for the platforms you want the Library to work on. In most situations, you will want to select macOS, Windows and Linux.

Now click Build. This builds the app as usual, but also creates a separate Library package file (LibHello.xojo_library for this example) that can be used with other projects.

Using a Library

Now that you’ve created your Library package, you can use it with other Xojo projects. The Library built above was created within a Desktop project, so it can only be used with other Desktop projects. So the first thing to do is to create a new Desktop project (call it MyTest), save it and close it.

Once it is saved, go to Finder or Explorer and place a copy of the LibHello.xojo_library file (from its build location) alongside this saved project file.

Go back to Xojo and open the MyTest project. The project will open normally, but the Library will also be loaded up as well. You can see this by showing the Xojo About window and going to the Plugins & Libraries tab. There you will see the Library name along with the information you entered about it earlier. (Double-click on the Library row to show the description.)

Going back to the MyTest project, you can now use the Library with it. Add a button to the window and have it call the StringReverse function the same way you did before:

Var stuff As New StringStuff
Var result As String = stuff.ReverseString("Xojo")

MessageBox(result)

Now run the project and it will use the class and its method just as if it is part of the project.

That’s the basics of how to create and use a Library. You can of course include whatever you want in the Library, but as with any library it is usually a good idea to keep things well-organized.

Considerations

• A Library package (which uses ZIP) contains compiled code and definitions of the public API in that code.
• Only a single Library project item can be added to a project when developing.
• A project can use any number of Library packages.
• For a built library to work on all OS platforms, then those platforms must be selected before building it.
• Libraries only support 64-bit builds.
• Library packages are placed alongside the project file and are loaded when the project is loaded.
• Library packages can also be placed in the Plugins folder. These libraries will be loaded separately for each project.
• If items in your Library have dependencies outside the Library, then the Library package will not be usable in another project without those dependencies. For example, if a Library class method references a class in the main project, then it will build without an error (because the main project is available), but if you use that Library in another project you will get linker errors.

Why a Preview?

We are referring to this initial version of Xojo Libraries as a preview release because it is very new and we want to give more developers a chance to test with it so we can iron out issues. We encourage you to try moving your existing reusable code collections over to a Library to help test, while also improving your workflow. If you have any open-source projects that are essentially a Library, you might try building them into a Xojo Library package as well.

You can make Library packages available publicly, but you should probably tag them as a preview, beta or test version until we remove the preview label.

Read more about Libraries in the Xojo Documentation. Check out these open-source projects on GitHub that have recently been updated for API 2.0 and now have a Library that you can download from the Releases section:

• Visual Basic Library
• FileMaker Library
• WinAPI Library

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

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