To demonstrate this, we’ll use the Desktop Toolbar example project that ships with Xojo. You can find it in the Examples section of the New Project window. Open this project using the Xojo 2025r3 IDE.

Once the project is open, locate the MainWindow in the Project Browser. Under MainWindow, select the WindowToolbar item and then choose its Opening event. At the top of the Code Editor for this event, add the following lines of code:

Var hdl As Ptr = Me.Handle
If hdl.Integer <> 0 Then
  Declare Sub AllowCustomization Lib "AppKit" Selector "setAllowsUserCustomization:" (hdl As Ptr, value As Boolean)
  AllowCustomization(hdl, True)
End If

It’s that simple!

Run the app and open the contextual menu by right-clicking (or Control-clicking) on the window’s toolbar. You’ll see a new Customize Toolbar menu item. Select it to open the standard macOS toolbar customization panel, where you can rearrange or remove items as you like. When you click OK, your changes are immediately applied to the current toolbar.

One important caveat: these customizations are not preserved between app launches. This happens because each toolbar must have a unique identifier that macOS uses to save and restore its configuration. Since the example toolbar does not provide one, the OS has nothing to store or retrieve. But… who knows what the future holds?

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

So, what is UI Compatibility Mode? It’s Apple’s way of ensuring that your app’s UI appears in macOS 26 and iOS 26 just as it did on previous OS versions. No Liquid Glass effects, no unexpected changes in control sizes or behavior, everything stays as you designed it. This means your pixel-perfect layouts from older OS versions, like Sequoia or iOS 18, will continue to look exactly as intended.

More technically, when UI Compatibility Mode is enabled, your app behaves as if it were compiled with an earlier SDK.

The caveat: Apple only guarantees this behavior while macOS 26 and iOS 26 are current. With the next major OS releases, this mode may no longer be available, so it’s a temporary solution.

The upside: At the time of writing, Apple is still refining these OS versions with point releases. If you need your app to run on macOS 26 or iOS 26 with full compatibility, you can enable UI Compatibility Mode in the Inspector Panel under Build Settings > macOS and Build Settings > iOS.

When enabled, both your debugged apps and the built versions (including those submitted to Apple via Publish) will look and behave on macOS 26 and iOS 26 as if they were compiled with the previous SDK. In fact, the behavior is even more consistent than if they had been compiled using the prior Xojo release.

Below, you can see how the same app appears when running on macOS 26 and iOS 26 with UI Compatibility Mode turned off (showing Liquid Glass and all the new UI effects), compared to how it looks when the switch is turned on:

The Last Word

All in all, macOS 26 and iOS 26 introduce a major UI overhaul, which can change the appearance of existing layouts. To help developers, Apple has added UI Compatibility Mode, which lets your apps appear on these new OS versions just as they did on previous releases—no Liquid Glass effects or layout changes. Technically, enabling this mode makes your app behave as if it were compiled with an earlier SDK. While Apple only guarantees this behavior for macOS 26 and iOS 26, it ensures consistency for both debugged and built apps, including those submitted via Publish.

UI Compatibility Mode gives you a choice: enable it to preserve your exact layouts across all OS versions, or leave it off to adopt the new macOS 26 and iOS 26 look and feel, which may require adjusting your UI for some quirks.

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

Getting Started

Jade uses Anthropic Claude as its engine, so before using Jade, you first need to sign up for an Anthropic API key to access Claude. You can do this from the Anthropic Claude Console.

From there you can create your account. After you’ve done that, you will want to get an API key to use with Xojo. Click on the “API keys” tab to see existing keys and create new ones. Click the “Create Key” button to generate a new key. In the dialog, give it a name to indicate its purpose.

When you click Add, the actual key will be shown. Copy it to the clipboard.

Note that you cannot see the key again after closing that dialog, but you can always create a new key at any time.

Now go to Xojo Settings and in the General tab, paste it into the “Anthropic API Key” field.

Go back to the Claude Console and click on the Billing tab to buy credits. Interacting with Jade requires credits. The amount of credits used depends on the complexity of your interactions. Until you get used to Jade and credit usage, you’ll probably want to start with a small amount, like $5, and disable auto-reload.

Using Jade

To use Jade, select Help->Ask Jade or click the Ask Jade button in the toolbar. You’ll get some short introductory text. Note: Using Jade requires an internet connection.

You interact with Jade similarly to a chat app by typing prompts in the conversation area (bottom section) and pressing Send. Jade will think for a moment and then display its response.

If Jade’s response includes Xojo source code you can click one of the buttons above the code block to copy the code to the clipboard or to directly insert it into the active code editor.

When interacting with Jade, keep in mind that although it remembers the context from the current conversation, it has no knowledge of prior conversations. Click the “Start Over” button to clear things and start a new conversation. Starting a new conversation is useful when switching to a different topic as it prevents Jade from relying on information you previously discussed that is no longer relevant.

The Export button saves the current Jade conversation to a JSON file which is a great way to save information you want to retain and refer to later.

Other Tips

• Jade currently uses Claude Sonnet 4, but this may change as newer models become available.
• The only thing Jade knows about your project is what type it is (Desktop, Web, iOS, etc.). If you want Jade to offer suggestions based on your code, you will need to copy/paste the relevant code into the Jade conversation area.
• Your Jade conversation is restored when the IDE restarts. If you get errors, ensure that you have valid internet access, that the API key is valid and you have a positive credit amount.

Wrap

We hope you find Jade helpful with your Xojo development. Remember, Jade in Xojo 2025r3 is the first version of an AI assistant for Xojo and will improve over time. In subsequent releases we expect to add more capabilities and project integration. Read more about Jade in Xojo’s Documentation.

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

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

macOS 26 and iOS 26

Over time, Apple has brought the user experiences of macOS and iOS closer together. macOS 26 and iOS 26, now aligned in version numbers, also share more similarities than ever in their user experience. These updates represent the most significant user experience changes from Apple since iOS was introduced in 2007 and Aqua for macOS seven years earlier. With such a big update, especially when designing elements to work on both large computers displays as well as small smartphone screens, it’s no surprise there’s some tweaking requiring after release. Clearly, Apple is still refining its platforms.

We continue to update Xojo as Apple defines its preferred user experience, ensuring that you can deliver the best possible experience to your users.

WinUI

We are also hard at work upgrading our Windows framework to WinUI, providing a modern user experience for Windows apps. You can see our progress in each release by enabling the Use WinUI (Experimental) option on the Advanced tab in Windows build settings. The “Experimental” label is a reminder that the feature is still evolving, and it will be removed once WinUI is fully ready. Our goal has always been to keep Xojo on a steady path, prepared for whatever challenges lie ahead.

Conclusion

On behalf of the entire Xojo team, I can say that we love what we do and we appreciate your support in allowing us to do it. We are Xojo users ourselves (after all, we make Xojo with Xojo) and we enjoy seeing what you make with it. With that in mind, feel free to tell us about your creations. Send your screenshots, descriptions and your story to hello@xojo.com.

Passkeys Demo

In this demo, we will be creating a new account using just our email. Using a platform authenticator, like Apple Passkeys or Windows Hello will make this pretty easy. They are integrated in the operating system and synced across devices. I will be using macOS with the integrated Passwords app, but this is supported in Windows through Windows Hello, or you could store, sync and use Passkeys using a Google Chrome Profile.

As you can see, there is no intermediate step. No need to use a separate app to store your passwords securely. A Passkey will be generated and stored in the authenticator in one simple step. This Passkey will be automatically synced across devices and available on my iPhone.

Opening the Password application, I already can confirm my new Passkey has been stored for “localhost”. Notice the user name is also there, meaning you won’t need to fill it during the login process.

The username isn’t important or even required, it’s just to display a friendly name for this user. A Passkey will include the user ID, which can be any arbitrary String you want. In my example, I’ve used the new Random.UUID method, but this is completely up to you. And this is transparent for the end user.

Now, let’s try to login:

That’s it!

Another thing to notice is, while I have several Passkeys for different websites, only the relevant Passkey can be used. This makes Phishing attacks useless. End users won’t be able to use a Passkey anywhere else, just on the website where it has been created. And also, users won’t be able to send their password by mistake to an attacker because … they can’t!

For web application developers, another interesting thing to note is that you won’t be able to store a Passkey insecurely. Even if your database gets compromised, a hacker won’t be able to use the stored public keys to authenticate those users with another service. To make it easier to understand, you will be storing a lock, not the key used to open it.

Other User Journeys

My demo is just the classic email / password sign up / sign in workflow, but without using a password. Passkeys is based on WebAuthn (part of FIDO2) and there are several ways you can use this technology in your web application. For example, you could use a shared computer and still be able to securely log in using your mobile. The platform will display a QR code you can read with your phone camera, and grant the access from your personal device.

In my example application, the user can sign up using different emails. If the Passwords app encounters more than one for my domain it will allow the user to specify the Passkey to use:

Xojo will take care of preparing the WebAuthn steps, verifying signatures and doing the common busy work for you. You will have to decide which workflow makes sense for your application and perform any further verifications, like sending a verification email on register, to ensure this user owns that account.

Multi-Factor Authentication

If you already require your users to authenticate with a username (or email) and a password, you could use WebUserAuthentication as a second factor. That means the user will need to provide something this person knows (a username and password combination) in addition to something the user has (the authenticator device)

Other common multi-factor authentication schemes are email magic links and time-based one-time passwords, “TOTP”.

More factors equal better security, of course. But as usual when it comes to security, you’ll have to find the sweet spot between secure and comfortable.

Usernameless + Passwordless Authentication … Wait, What?!?

“How can I authenticate without providing my username or email?”. This is where real new possibilities arise. When you use a username with a password that only Chuck Norris and you know, this becomes a “proof of identity” (at least in theory, in practice a hacker could compromise an account using a weak password)

When using an authenticator without a username or password, it becomes a “proof of possession” of the authenticator device.

Again, think about it as a locker’s lock and a key. Everyone can see the lock, but only people with the correct key can open it. The public key would be the door’s lock, while the authenticator device would be the key. You can share the key with another person you trust to grant this person access to the contents behind that door. The difference with a real-life lock is that we will be using a really secure one, with a security key.

As long as you can proof you have a valid “key” to authenticate, you are granted to continue.

Consider the following scenario. The company could have a web application that uses a traditional username + password authentication but, for really special activities, the user needs to authenticate with a physical USB key authenticator device that is shared by everyone in the office.

Other use cases are obviously when privacy is involved. A private journal, or a private blogging service, voting. The inconvenience in this case is the user won’t be able to recover the account if they lose access to the authenticator. In this case, you might want to offer a different recovery solution, like printing a very long recovery code. If they also lose the recovery code, they will permanently lose the account.

How To Use The New Control

As you do with any other non-visual control, like a WebTimer, you can just drop the new WebUserAuthentication control into your WebPage.

Then configure its properties. The most important one is the Domain field. It must match the domain name where your application will be deployed. If you want to test it locally without using HTTPS, it must be “localhost” (“127.0.0.1” won’t work)

There are four events available:

You can use RegistrationSucceeded and AuthenticationSucceeded to interact with your Database, store the details and redirect the user to their dashboard.

In RegistrationSucceeded, a WebAuthenticationCredential will be given to you. This is a data transfer object with the following properties you need to store in your database:

• ID
• PublicKey
• AuthenticationAttempts
• DisplayName

Error will be fired when something goes wrong. A message will also show with the details about what happened, but it isn’t meant to be shared with the end user. During the sign up and sign in processes, you should display generic messages for security, to avoid letting bad actors know what’s going on. If you need to inform the user something related to these messages, you can send them an automated email instead.

CredentialRequested will be fired during the authentication ceremony. A userId and a credentialId will be given to you, and you should return a new WebAuthenticationCredential instance with the details coming from the RegistrationSucceededEvent.

Also, when AuthenticationSucceeded happens, the event will come with an authenticationAttempts parameter. This will be an incremental value used to update your credentials. This is part of the WebAuthn protocol sign in ceremony used to detect cloned authenticators, which is supported by Xojo. Please notice this value might come always as “0” when using Safari, for example, but Google Chrome will increase its value each time.

You can initiate a Registration or Authentication ceremony by calling Register or Authenticate, respectively.

• Register(userId As String, username As String = “”, displayName As String = “”)
  The parameter userId is required, the new credential will be built specifically for it. It can be anything that makes sense in your application, like an auto-incremental number or a random UUID . The other parameters are meant for giving the credential a friendly name. The username could be a nickname, or an email. In workflows where you allow the user to store more than one passkey, the displayName could be something like “Backup key”.
• Authenticate(Optional allowCredentials() As String)
  This will initiate the authentication ceremony. You can optionally pass an array of credential IDs, allowed for the user trying to get access to the protected resource.

Adoption and Compatibility

Not every user may know they even exist, what they are, how they work or if they will be more secure than using their pet’s name and birthdate. This can cause some friction. Other users that adopted the usage from day one might have at least two physical USB keys. They expect your application to allow them to enter more than one, just in case they lose their main USB key.

Passkeys are here to stay and their adoption will continue growing on web services. That said, depending on the combination of operating system and browser, there are some gotchas. Google Chrome or Firefox should work on every operating system. Apple users will probably obtain the best user experience if they’re tied to this ecosystem. Linux users using alternative browsers could experience some challenges.

If compatibility is a must for your application, you should still offer an alternative to Passkeys. For example, legacy passwords, or “magic login links” sent by email.

Wrapping Up

We are sure Passkeys will be the norm in the coming years. Read more in the Xojo Docs. Xojo is ready to embrace them and you can start adopting them in your Xojo Web application today!

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

We’re taking a similar approach with our WinUI transition. We began with the DesktopXAMLContainer and are continuing by updating our Win32 controls to their WinUI counterparts, aiming for steady progress without disrupting existing workflows.

What can you look forward to in 2025r3?

We’ve expanded our WinUI offerings in this release with a broader set of updated controls. While 2025r2 introduced only a handful of WinUI-backed controls, 2025r3 builds on that foundation by updating a much larger group, including: BevelButton, Label, UpDownArrow, DateTimePicker, ComboBox, PopupMenu, RadioGroup, SegmentedButton, DisclosureTriangle, MoviePlayer, SearchField, TextField, and TextArea.

What are the benefits of using WinUI?

Win32 controls have been the foundation for many Windows apps, but WinUI introduces capabilities that traditional Win32 controls don’t have. Here’s a comparison to highlight some of the differences:

A Win32 DesktopLabel with a colored emoji is rendered in black and white.

Compared to the WinUI version with a colored emoji.

A Win32 DesktopTextField containing right-to-left text isn’t automatically recognized as such, so it renders left-to-right.

Compared to the WinUI version which can automatically detect right-to-left text and formats accordingly.

A password field (via DesktopTextField) with primitive support on Win32.

An actual WinUI version of their PasswordBox control with a preview widget.

A Win32 DesktopComboBox which does not support separators.

A more modern looking WinUI version with built-in support for separators.

A Win32 DesktopDateTimePicker with a dropdown calendar, but does not support dark mode.

A more modern looking WinUI version that also supports dark mode.

Win32 dark mode support is limited.

WinUI dark mode support is easier on the eyes.

The Win32 DesktopMoviePlayer is very dated.

WinUI has a much more modern look and feel.

Opt-in to WinUI

If you’d like to preview how your apps look and feel with WinUI controls, open the Windows build settings and check the options under the Advanced widget tab. Selecting “Use WinUI” applies WinUI styling to your desktop controls while keeping them scaled to your existing Win32 control bounds. Opting into “Native Control Sizes” gives you a more accurate representation of a true WinUI app, using the larger default font size and correspondingly larger controls.

More Work Ahead

As we continue down this path, we’re uncovering pain points that developers face when using WinUI controls in a Win32 environment—challenges Microsoft is no doubt familiar with as well. It will take time before we can fully move away from Win32 controls/windows and embrace WinUI, but we’re steadily heading in that direction. Thanks for joining us on this experience, more to come!

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

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

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

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

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

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

Is the DesktopGrid a replacement for DesktopListBox?

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

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

Performance Caveats to Consider

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

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

Wiring the Grid

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

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

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