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

What this project includes:

• Interactive command-line interface to manage tasks
• Commands to add new tasks, mark tasks complete, list all tasks, and remove tasks
• Simple file saving/loading to keep your tasks persistent between sessions
• Clean and modular code architecture for easy customization or extension

This project highlights how Xojo can be used beyond GUI applications, making it ideal for automation scripts, tooling, or quick utilities you want to run directly in the console (Mac, any Linux flavor, Windows) without the overhead of a full UI.

You can check out the full source code and try it out yourself at GitHub: Xojo-Console-Tasks.

Give it a spin, modify it to suit your needs, and share your enhancements or questions with the Xojo community. This is a great way to get comfortable with console application design in Xojo and to stretch your coding skills in a new context.

Stay tuned for next month’s project as we continue our journey deep into the many facets of coding with Xojo!

Year of Code Project

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

How to Play:

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

The Prizes:

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

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

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Out With The Old

The old database connections were quite limiting, requiring you to create a new connection and re-enter all the parameters whenever one changed. With our new Database Connection items, you can now easily update specific connection parameters directly in the inspector.

Additionally, you can now choose whether the item will auto-connect or if you prefer to connect to it later in your code.

Connecting to a Specific Database

There are times when you need to connect to a database for debugging and testing, but for the final builds, you want to connect to your production database/server. Setting this up correctly with the old database connection method required creating two separate connection items—one for debug and one for release. With the new Database Connection items, this process is much simpler and fits more easily into the build process. You now have several new Database Connection subitems that can be customized based on the stage of your build. These subitems are linked to the Stage Code in your Shared Build Settings, ensuring that when you build a final release, your database connection uses the correct settings automatically.

Additional Database Features

In addition to this change, there are two new database APIs that may be useful to you:

1. A new method, IsConnected, has been added to the SQLiteDatabase, ODBCDatabase, PostgreSQLDatabase, and MySQLCommunityServer classes. This method returns true if the connection is still active, and false if it is not.
2. We’ve enhanced Database.AddRow with a new signature that returns the unique ID of the newly inserted row. This feature is supported for SQLiteDatabase, ODBCDatabase, PostgreSQLDatabase, and MySQLCommunityServer classes. It is recommended to use this new API instead of the deprecated SQLiteDatabase.LastRowID and MySQLCommunityServer.LastInsertedRowID

Let’s explore how the new Database.AddRow feature can assist you. Previously, only SQLiteDatabase and MySQLCommunityServer had APIs to retrieve the unique ID of the last inserted row. Now, PostgreSQLDatabase and ODBCDatabase also have this capability by using the new Database.AddRow(tableName As String, row As DatabaseRow, idColumnName As String = "") As Integer

The new aspect of this signature is the idColumnName parameter and the return value. For databases that support the SQL RETURNING clause, the idColumnName specifies the column whose value will be returned. For databases that do not support the RETURNING clause, we will use the suitable method for each specific database to return a unique value.

We recognize the significance of databases in your Xojo apps. So with these updates to database connectivity for your desktop, web and console apps, and the addition of new features, we aim to make your database programming easier and more efficient.

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

Xojo Web is an excellent way to expose the features of your electronics projects without having to attach any screen to them. It’s never been easier to build a Web GUI for your smart clocks, drones, POS, domotics, robots or just some automation services. Thinking about building a solar powered server to automate your tweets? Why not!

If you prefer, you can just expose a Web API instead that can be remotely consumed from another device.

What Raspberry Pi boards support ARM 64-bit Linux OS?

• Raspberry Pi Zero 2
• Raspberry Pi 3
• Raspberry Pi 4
• Raspberry Pi 400

Preparing your Raspberry Pi

The easiest way to get your operating system ready is by using the Raspberry Pi Imager.

At the moment of writing this article, it selects the 32-bit flavor by default. If you have one of the supported boards, go ahead and try Raspberry Pi OS (64-bit) or Raspberry Pi OS Lite (64-bit). The later won’t include any desktop environment, you’ll have to access by SSH.

Select your SD Card storage and press on Write. Optionally, if you want to set a hostname for your board, enable SSH, or even configure your Wifi, press on the gears icon.

In just a few minutes you will have a ready to boot SD card for your Raspberry Pi.

Remotely debugging your projects

This is one of my favorite features of Xojo.

In your Xojo installation Extras folder, you will find a “Remote Debugger Console” and “Remote Debugger Desktop”, that also works for your Linux 64-bit OS.

Depending on which flavor of Linux you’ve selected in the previous step, send the Console or Desktop ZIP to your board, run it and configure the settings.

Inside Xojo, go to Preferences and press on the Debugging tab.

That’s it. Now you will be able to remotely run and debug your applications. Add a few breakpoints and the execution will stop as soon as it reaches it, allowing you to explore the current state.

Deploying the final version

Once you’re ready to build the final version of your application, all the wires attached and components soldered, the last step is to “Deploy” your application.

There is a tutorial covering this step in detail: Deploying Web Apps on Linux.

If you create a Raspberry Pi project, please make sure you open a Forum thread. The Xojo community loves seeing this kind of projects!

What will you build?

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.

Xojo Pro includes support for every platform:

• Desktop – Cross-compile for Windows, macOS X & Linux.
• Web – Deploy web apps as standalone apps or to Xojo Cloud.
• Mobile – Make apps for iPhone and iPads (iOS) and Android.
• Pi – Make apps for Raspberry Pi and other single-board computers.
• Console – Make apps with no graphical user interface that run from the terminal, command line or as background processes.

In addition, Xojo Pro developers enjoy the following benefits:

• Technical Email & Phone Support
• Access to Xojo pre-releases
• License activation on 3 machines
• First access to Consulting Leads

Xojo Pro is $799 and a new license includes build access to new Xojo releases for 12 months. Your Xojo license is perpetual, but access to building apps with new Xojo releases is limited. After 12 months you can renew your access to build apps with new releases or continue building apps with the older releases, indefinitely. You are never required to renew and can do so anytime to access new features and supported platforms. Your apps built with Xojo are yours forever.

Already have a Xojo license? Upgrading it to Xojo Pro will earn you a discount. We’ve made it easy to Upgrade to Xojo Pro, just log in to your account, go to your licenses page and select the license(s) you wish to upgrade. The more licenses you select, the greater your discount. After you have selected the licenses to upgrade, choose “Upgrade to Xojo Pro” to see your personal upgrade discount in the store.

Questions about Xojo Pro or upgrading your existing Xojo licenses to Xojo Pro? Email me anytime at hello@xojo.com.

Think you need more? Look into Xojo Pro Plus, developed for businesses that depend on Xojo.

A Worker achieves this by running its code in a Console app. One or more of these console apps are started based on your Worker settings. Since these run as Console apps, the OS treats them as separate processes and spreads them out amongst available CPU cores.

Note: For now, Worker can be used with Desktop projects, but we plan to make it available for Web projects in the future.

When run in Debug mode, Workers use Threads to simulate separate Console apps to make debugging easier. This means that when debugging everything still runs on a single CPU core. Build your project to allow your Workers to run on multiple CPU cores.

Worker Overview

Add a Worker to your projects using the Insert toolbar or menu. This creates a special Worker object in your project which provides properties and events for controlling how it operates.

There are three properties you can adjust in the Inspector for a Worker.

• Core Percent: This indicates the percentage of CPU cores that should be used. For example, if you have an 8-core CPU, enter 50 here to limit the Worker to 4 (50% of 8) CPU cores.
• Maximum Core Count: This indicates the most cores you want the Worker to use. This works in conjunction with Core Percent. For example, if you have a 12-core CPU with Core Percent set to 50 then that would mean use up to 6 CPU cores. If you then set Maximum Core Count to 4, then the Worker will use no more than 4 (rather than 6).
• Project Items to Include: When this is blank all classes and modules in your project are included in the Worker Console project for use. However you may not need everything, so you can choose to be specific about which supporting classes and modules you want to include (one project item per line).

The Worker object itself has five events you use to project jobs for the Worker to do.

JobRequested: When a Worker is first started, it requests a job which calls this method in your app. Here you can return a String containing details about the Job that the Worker will run. You can return information here such as a path to a file, a key to a database table, a URL, or whatever else makes sense. However, you should avoid passing round large amounts of data as that is slower and will use more memory. Instead, allow the Worker to get what it needs based on the information you return here. When there are no more jobs, return an empty string to tell the Worker it can quit.

JobRun: The code in this event runs in the Worker Console app where it can make use of multiple CPU cores. The parameter contains a String with the information that was returned from JobRequested. Remember that this code is independent and should not refer to any values that were set in your app as they won’t be available in the Worker. The only data the Worker gets is what is passed in, which it can then use to look up additional data elsewhere. You can return a String from this event to provide information about the job that just finished running. In addition, when a job is finished a new job is requested by calling JobRequested.

JobCompleted: When JobRun finishes, the JobCompleted event is called and the value that was returned from JobRun is provided here. You can use this method to update your job list or do other housekeeping.

JobProgressed: You can call the SendProgress() method to send progress information back to your app, which you can process in this event.

Error: The error event is called if there was an error running a job. You will be provided with the details of the job that caused the error so you can log it or add it back to a queue so that it can attempt to run again.

Once you have implemented the events (at a minimum JobRequested and JobRun), you start a Worker by calling its Start method.

Workers automatically stop when they have no more jobs to do or if they lose communication with your app.

Word Counter Example

There are a couple Worker example projects that are included with Xojo: PictureResizer and WordCounter (Examples/Worker). In particular, the Word Counter example shows how Worker can be used to improve performance by using multiple CPU cores. Without Worker, counting the words in 4 text files takes about 12 seconds. With Worker using 4 CPU cores, it takes about 4 seconds.

The WordCounter example has a simple class (called WordCounter) that counts words (intentionally) slowly.

There is a Jobs() array on the WordCountWorker that contains the paths to the text files to word count. In the JobRequested event, the first item in the array is removed from the array and returned so that JobRun can work on it.

JobRun uses the WordCounter class to load the text file and count its words, returning the word count and the path of the file it counted.

JobCompleted updates the main window with the word count.

For more information about Worker, refer to the Worker topic in the User Guide.

This is the first iteration of the PDFDocument class and we are very aware of the things that we will be adding in future releases that are not in 2020r1. Nevertheless, this first set of features will let you create many of the documents you need in Desktop, Web and Console.

In addition, you’ll be glad to know that both the text and the geometric forms you add to your PDF documents are vectorial! Except those generated when “printing” PDF documents from your Reports; those will be vectorial once we add Obejct2D support to the PDFDocument class.

The fact that both text and geometric forms are vectorial in your PDF documents means that these will be rendered with  100% quality, independently the scale factor you (or your users) may be using once they display them with any PDF viewer utility or App.

In addition, because the text is vectorial it will be searchable using any PDF utility with text search capabilities; and, for example, when using the Preview app on macOS, the data detector’s technology will be able to catch and act on some specific data like telephone numbers or postal addresses.

Creating a PDF Document

As when using any other class from the Xojo framework, start by creating a new instance for the PDF document. So, in this case you only need to use:

Var MyPDF As New PDFDocument

It will use the by default constructor, creating a document with a letter size blank page.

If you want to specify a concrete page size, you may use any of the included Enumeration values, for example:

Var MyPDF As New PDFDocument(PDFDocument.PageSizes.A4)

Or any other arbitrary size:

Var MyPDF As New PDFDocument(500, 500)

So, in this case, the PDF document will be created with a 500 width x 500 height pixels for the page.

Drawing into the PDF Document Page

You’ll be able to include text, Pictures and some geometric forms like Lines, Circles/Ovals, Rectangles/Rounded Rectangles (both in their filled or outline variants). For that you can use the same methods and properties you use when drawing over any regular Graphics context.

For example, the following code snippet will draw a filled circle centered on the PDF page:

Var g As Graphics = MyPDF.Graphics

g.DrawingColor = &C00ff00

Var x, y As Integer

Var size As Integer = 200
Var offset As Integer = size / 2
x = MyPDF.Graphics.Width / 2
y = MyPDF.Graphics.Height / 2

g.FillOval(x - offset, y - offset, size, size)

While the next one will draw the “Hello PDF World” text centered on the page and over the previously drawn circle.

Var helloWorld As String = "Hello PDF World"

g.FontUnit = FontUnits.Pixel
g.FontSize = 20
g.Bold = True
g.DrawingColor = &cffffff

Var textWidth As Integer = g.TextWidth(HelloWorld) / 2
Var textHeight As Integer = (g.TextHeight / 2) - g.FontAscent

g.DrawText(helloWorld, x - textWidth, y - textHeight)

Adding New Pages to the PDF Document

In order to add a new page to your PDF document you only need to call the NextPage method on its graphic context:

g.NextPage

And that means that, from now on, all the drawing commands will be made on the new page. For example, let’s use some large fragment of text so it will be centred on the new Page (this one will be the classic “Lorem Ipsum” text, stored in this case by the kLoremIpsum Constant):

Var textWrap As Integer = 200

x = g.Width / 2 - textWrap / 2
g.FontSize = 10
g.Bold = False
g.DrawingColor = &c000000
g.DrawText(kLoremIpsum, x, 20, 200)

At this point, our PDF document will be as the one displayed in the following screenshot:

Adding Pictures

Let’s say we did add the “Trees” Picture to our Xojo project. We will be able to draw it on the desired coordinates (and with the desired size of 50 x 50 pixels) over the PDF document page using the following sentences:

g.DrawPicture(Arboles, 20, 20, 50, 50)
g.DrawPicture(Arboles, g.Width - 70, 20, 50, 50)

Metadata

You can set the usual metadata to the PDF documents using Xojo. For example:

MyPDF.Author = "Xojo Developer"
MyPDF.Creator = "My Fancy App"
MyPDF.Title = "PDF Document"
MyPDF.Subject = "My First PDF Document"
MyPDF.Keywords = "Xojo, PDF, Code, Multiplatform”

Once you save the document to disk, this information will be available (and displayed) as part of the PDF properties- for example, using the Preview app on macOS:

Saving a PDF Document to Disk

In order to save the PDF documents created with Xojo to disk, you’ll need a valid FolderItem instance. Next call the Save method on the PDF document instance and give to it the FolderItem instance as the parameter. For example:

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

f.Open

In this case, the last line of code will open the PDF document using the default app or utility set on your OS.

Included PDF Examples

These are just some of the basics when creating and working with PDF Documents in Xojo, and I encourage you to explore the PDF project examples you’ll find inside the Example Projects > PDF folder. For example, there you can find how to create PDF documents that look the same both when using a regular Graphics context and the PDFDocument instance, including composing documents with data retrieved from a database or any dynamic data source, both in Desktop and Web.

In addition, you can find how to create PDF documents with more complex layouts, combining text, geometric figures and pictures, or even creating a basic graphic chart using rectangles.

Coming Next!

We are well aware of all the possibilities offered by the PDF standard! Future features coming to the PDFDocument class include support for Object2D, full Unicode text support, hyperlinks, document ciphering, and much more! We also intend to support PDFDocument with iOS in the future.

sudo apt-get install libunwind8

The Raspberry Pi OS (Raspbian) does not automatically update itself. Since it is always a good idea to keep your Pi up to date, you can do it easily from Terminal using these commands:

sudo apt-get update
sudo apt-get upgrade

To learn more about Raspberry Pi and Xojo:

• Getting Started with Raspberry Pi
• Programming the Raspberry Pi with Xojo book

And don’t forget, you can build Console and Desktop apps for Raspberry Pi with your free Xojo license.

UPDATE: Now with Xojo 2019r1, you can develop and build console and desktop apps for the Raspberry Pi for free! Download today and get started! Xojo Pi supports Raspberry Pi 2, 3 & 4.

Back at XDC 2015 when we announced Xojo would be adding support for the Raspberry Pi, we thought it was a fun extra for Xojo users. We were not expecting the overwhelming excitement and interest from the Xojo community and makers around the world! To celebrate Pi Day like the true geeks we are, we’re making Xojo Pi licenses free from Pi Day & forever!

Email hello@xojo.com for your free Xojo Pi license activation code.

Share the new with you friends, we’re on Twitter, Facebook, Instagram and LinkedIn.

UPDATED: 4/8/2019

So I have a challenge for you, you can download the already canned Xojo class ready to use … or you can continue reading and discover how easy is to use Xojo to generate your PDF files!

The service we are going to use is the OpenSource software Docverter, able to convert any plain, HTML, Markdown or LaTeX file to PDF, Docx, RTF or ePub using a simple HTTP API. In my tests it worked like a charm from the HTML + CSS returned from Markdown Parser class of my own.

In fact it is possible to use this service stright from a Shell class instance, but I’ve found it more portable and multiplatform to wrap it in a Class so you can simply drop it in your project, passing the file or files you want, and specifying the conversion you want to get back; as simple as that!

For that API wrapper we are going to create a new class derived from HTTPSocket. Let’s name it HTTPDocConverter and put as the next step these String constants that will ease its use:

• kDOCX As String = "docx"; scope: public.
• kePUB As String = "ePub"; scope: public.
• kMOBI As String = "mobi"; scope: public.
• kRTF As String = "rtf"; scope: public.
• kRemoteAPI As String = "http://c.docverter.com/convert"; scope: private.

I think that is a good habit to get accustomed to constants wherever Strings or other frozen values are involved in order to minimize possible minor bugs in the code.

Now it is time to implement the class Constructor passing along three parameters that will simplify its use:

• convertDataTo As String. This is the text that identifies the format we want our document converted to and that is why we defined the Constants in the previous step.
• inputFile As folderItem. A valid FolderItem file pointing to the file we want to use as the source for the conversion process.
• notification as callback. This is new Delegate Type we will define in the next step, and that will be used by the class to, well, notify of the process completion. This way, your code and UI will not be locked.

So our class Constructor will have the following signature:

Constructor( convertDataTo As String, inputFile As FolderItem, notification as callback )

Once we add the Constructor method, the Xojo IDE will put the right class initialization here, and we will complete the code with the following sentences:

Super.Constructor
registeredCallback = notification
encodeRequest( inputFile, convertDataTo )

Time to add to the class a new Delegate Type (Insert > Delegate), using the following signature in the Inspector Panel:

• Delegate Name: callback
• Parameters: content As String, documentType As String
• Scope: Private.

That is: our class will accept as a callback Delegate any method that accepts two strings. In fact our class will return the already converted data into the argument content, and also the document type used for the conversion into the documentType argument.

With our Delegate already set, it’s time to add the registeredCallback Property to the class, and that will be responsible to point to the Delegated method passed to the class instance throught the Constructor:

• Name: registeredCallback
• Type: callback
• Scope: Private

In fact, let’s add two more Properties:

• Name: convertedToType. This one will contain the conversion format.
• Type: String
• Scope: Private

• Name: receivedData. This property will contain the converted data received from the remote service.
• Type: String
• Scope: Private

Encoding the Post Request … the right way

With all our properties set, it is time to add the Method encodeRequest. Here is where we will take care of constructing our Post Header request including the data for the source file we have to send to the remote URL, along all the required stuff. Create the Method with the following signature:

• Method Name: encodeRequest
• Parameters: inputFile As Folderitem, convertdataTo as String

And write the following snippet of code in the resulting Code Editor:

Dim formData As New Dictionary
formData.Value("input_files[]") = inputFile
formData.value("from") = "html"
formData.value("to") = convertDataTo
convertedToType = convertDataTo
Dim boundary As String = ""
Boundary = "--" + Right(EncodeHex(MD5(Str(Microseconds))), 24) + "-reQLimIT"
Static CRLF As String = EndOfLine.Windows
Dim data As New MemoryBlock(0)
Dim out As New BinaryStream(data)
For Each key As String In FormData.Keys
  out.Write("--" + Boundary + CRLF)
  If VarType(FormData.Value(Key)) = Variant.TypeString Then
    out.Write("Content-Disposition: form-data; name=""" + key + """" + CRLF + CRLF)
    out.Write(FormData.Value(key) + CRLF)
  Elseif FormData.Value(Key) IsA FolderItem Then
    Dim file As FolderItem = FormData.Value(key)
    out.Write("Content-Disposition: form-data; name=""" + key + """" + "; filename="""+inputFile.Name+""""+ CRLF)
    out.Write("Content-Type: text/html" + CRLF + CRLF)
    Dim bs As BinaryStream = BinaryStream.Open(File)
    out.Write(bs.Read(bs.Length) + CRLF)
    bs.Close
  End If
Next
out.Write("--" + Boundary + "--" + CRLF)
out.Close
Super.SetRequestContent(data, "multipart/form-data; boundary=" + Boundary)

Calling the remote API

Now that the hard part is complete, we are going to add the Method getConvertedFile, in charge of call the remote API:

• Method Name: getConvertedFile
• Scope: Public

And write this simple line of code in the Code Editor:

Super.post( kRemoteAPI )

This single line fires all the magic behind the scenes, now in order to get our response we need to add the Event PageReceived to our class, writing the following code in the resulting Code Editor:

If registeredCallback <> Nil Then
  registeredCallback.Invoke content, convertedToType
End If

If you want, you can also add the Error Event, so you can raise or inform about any error during the process.

Testing our class!

In order to test the class, and convert some documents along the way, add a new Method to the project Window (let’s assume its a Xojo Desktop Project). This is the one we will use as Delegate for the callback once we receive the converted data:

• Method Name: conversionCompleted
• Parameters: convertedData As String, documentType as String
• Scope: Public

And write the following code in the resulting Code Editor for the Method:

Dim f As FolderItem = GetSaveFolderItem("", "ConvertedFile." + documentType)
If f <> Nil Then
  Dim tof As TextOutputStream = TextOutputStream.Create(f)
  If tof <> Nil Then
    tof.Write convertedData
    tof.Flush
    tof.Close
  End If
End If

Add now the Open Event to the same Window and write the following code, this is the one in charge of creating our class instance and firing the conversion process. In this example converting the source file to a PDF file (you only need to change the file format constant to get other kind of documents as result):

Dim f As FolderItem = GetOpenFolderItem("")
If f <> Nil Then
  Dim post As New HTTPDocConverter(HTTPDocConverter.kPDF,f, AddressOf conversioncompleted)
  post.getConvertedFile
End If

Creating PDF Files without Internet connection

What if you need to generate PDF files without having an active Internet connection or because you handle confidential information? Well, in these cases I’m sure you’ll find of interest the wkhtmltopdf tool/library.

Add it to your product bundle/folder or directory during the compilation process and you’re set!

In this case, you have to invoke it from a Shell instance passing HTML as the source file and getting the PDF as result. The downside is that the distributable product will be weighter (47 Megabytes)! Not a big problem these days, anyway.

The Last Word

As you have seen, with a couple of methods and Events we were able to create a multiplatform Class that works in 32-bit and 64-bit targets for Desktop, Console, web and Raspberry Pi deployments. I’ve been able to create PDF, DOCX, RTF and even MOBI files in no time!

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

*Read this post in Spanish

It’s been suggested that this should be easy to do. Just make threads preemptive (so that they will then run on any available core) and voila! Unfortunately, it’s not that simple. Let’s look at why the current threads are not preemptive. It’s hard for you, the developer, to work with preemptive threads. Some languages, like Java, have language features built in to them to try and help make this less work, but it is still hard to get right and very hard to debug when you don’t. Much of the framework would need updating to be thread safe and your application’s user interface is not thread safe on any platform because the operating systems themselves don’t have thread-safe user interface code. If you access something from a pre-emptive thread and that something is not thread-safe, there’s a very good chance your application is going to crash. We have had to go to a lot of extra work just to make the threads you have today work without causing problems.

The Xojo language already has functions like mutex and semaphores that help you make a multi-threaded program. But you have to protect every place you might set a value that could be shared by many threads. This would mean protecting any globals and pretty much anything that is not local to the method or the thread being executed. That’s very different than what you have to do today and a lot more work. It’s just not simple or easy to use the way most of Xojo is designed to be.

The end goal is to use all cores and thereby make your software more responsive, faster, or able to handle more data, or do more things all at the same time. There’s been a way to do this for as long as Xojo has supported building console applications. The design is to create a main application (GUI or not) and use other helper applications to run separate tasks. The main application and the helpers can communicate in any one of several ways: IPCSockets, TCPSockets, UDPSockets, XML, files, or just about any other way you can dream of. The upside to this way of solving the problem is you can design and implement the main application and the helpers independently and use the debugger to debug each independently. You can use any data in either program in the same way you always have. You don’t have to worry about the framework being thread safe as the helper and main application run as completely separate processes with their own memory space. Most importantly, you can do this today.

I’m not going to say it’s simple. You have to think about what portion of your application can be segmented out into a helper console application. You have to design the communications between the main and helper applications. You have to write, test and debug them. But you don’t have to worry about variables changing mysteriously because some other thread changed the value. You don’t have to use lots of mutexs or sempahores to block other threads from altering things when you least expect them. And you can use the entire framework that is available to console applications. Last but not least, you can run as many instances of these helper applications as your computer (or all the computers available to you) can run.

If you think you need preemptive threads today, try the helper application approach and I think you’ll be pleasantly surprised at how well it works.

For more information: Take advantage of your multi-core processor

Like many in-house solutions, the demand on Server Ranger increased over time and it became a more vital part of my business.

Growth

Not just more clients, but clients with varied requirements, including monitoring of mail servers were depending on Server Ranger. Plus, I was starting to share some of the workload with less-techy people who had a hard time grasping my little Terminal app. It was time to move it from a console project to a fully-fledged desktop app, making it more flexible and more friendly. So, I created a brand new Xojo desktop project and started mocking up the app.

It’s fine to mock an app up in Sketch, Photoshop or even Keynote (my personal favorite – no, seriously, it’s great for mock-ups). But there is often a compelling reason to mock-up your app right in a RAD tool like Xojo because what you have at the end of the mocking-up process is a working app, not just a wireframe. Granted, your app won’t do anything yet but you can nevertheless build and run the app on real devices and get a feel for the flow of the app as you move around Views and Windows. It looks and feels like a real, native app, because it is.

So, I took my desktop mockup and integrated it with the original console project and I pretty much had a working app. But to do this right I used MVC.

MVC

Model-View-Controller (or MVC) is a an architectural pattern that assists in the fundamental design of your app. If you’ve never used it, you’re probably getting ready to skip the rest of this post but let me give you two good reasons why everyone, including Xojo developers, should be using MVC. First, it’s actually pretty easy to take advantage of the basics of MVC if you follow a few simple rules when developing your next Xojo project. And secondly, MVC will help you take maximum advantage of Xojo’s cross-platform abilities. Let me explain.

MVC asks you to think of the objects in your app and sort them, in your head, into three categories – Model objects, View objects and Controller objects.

– Model objects manage the data and logic in your project.

– View objects are what the user sees. Anything that represents information to the user.

– Controller objects are the glue in the middle. The View talks to the Controller which then talks to the Model.

MVC In Practice

If you’re new to this, it probably still sounds very abstract so let me put it into the context of a new Xojo project and then we’ll return to the benefits of all of this. I should say that there are many ways to implement MVC so I’m not about to give you some perfect, academic MVC example, but I will try to give you real-world, pragmatic examples.

Let’s start with the Model. I said earlier that Server Ranger started life as a console project which was in effect largely Model objects. It did processing in the background and recorded results. There was nothing in the way of user interaction and practically nothing in terms of what the user could see happening. Server Ranger’s Model layer largely consists of instances of a Server class. Each site or server that a user adds to Server Ranger is another instance of the Server class. Each of these instances process its own information and retains its own records. They are self-contained and don’t care how, or if, that data is ever presented to the user.

When I later mocked up the desktop version of Server Ranger, I was effectively designing the View part of MVC. It was all the stuff that the user could see and interact with. It didn’t do anything or process any data or retain any results. And that’s just fine. Server Ranger’s View layer therefore consists of custom Containers, charts, Xojo’s built-in ListBox, Labels and Canvases.

So how do we tie this together? If the View layer never talks to the Model layer, how does the app work? The answer is in the Controller layer. In Server Ranger, the Controller is a singleton object. For simplicity, I literally call this object ‘Controller’. When a user clicks on a PushButton, the only code in a PushButton’s Action event is a call to a method in the Controller. It’s this Controller method that talks to the Model layer and asks it to retrieve the data that the user requested when he/she clicked the PushButton. The Controller then says to the View layer, “hey, I have some information for you” and it’s up to the View layer to grab that information from the Controller, if it so chooses. But the PushButton itself never communicates directly with the Model layer.

The Future of Server Ranger and Benefits of MVC

Most of my customers install Server Ranger on a single Mac which then monitors their various sites and servers. But I know of a customer who has several offices throughout the world and he has a Mac in each office with Server Ranger on it. Wherever he is in the world, he can get a notification that there is trouble somewhere in his infrastructure. But ultimately, Server Ranger is a single-instance stand-alone project.

On our roadmap for this Fall, we plan to build a subscription-based Web version of Server Ranger, also built in Xojo. They can sign-up for our service which will have multiple instances on each continent, all coordinating and updating each other and the user will receive emails or SMS alerts when problems occur. Using MVC, the basic heart of Server Ranger will be retained because the Model will largely be the same as it was in the stand-alone product. Remember, the Model knows nothing of how the information is displayed and it doesn’t care. It just does its work and remembers its results. Naturally, the View layer will be different but because the View layer on the macOS product only had calls to the Controller layer, there’s nothing to decouple from it.

The stand-alone product will similarly expand with new features. I also plan to target the Windows platform and iOS as well – though I’m still investigating that one. But whatever platforms we end up targeting, using the MVC design pattern will help bring the core of the product to a new platform much faster. And that helps you, as a Xojo developer, get more bang for your Xojo buck.

We all know how quickly Xojo helps you get an app up and running but I urge you to take a little time to consider the architecture of your next app as you can reap benefits down the road. You might start out as I did with Server Ranger’s rather modest goals but over time you might find your needs expand and you want to start targeting other platforms. Architecting your app using MVC from the start, helps you do that more efficiently.

Guest Post from Gavin Smith. Gavin Smith has been using Xojo (and its predecessors) since 1998 and has been running LibertyApp Ltd for 8 years. Find out more about Server Ranger or purchase it. Please feel free to email me at gavin@libertyapp.com or follow me on Twitter @gvnsmth.

My Raspberry Pi 2 sits on my desk next to one of my speakers. It’s not hooked up to any display. I use a combination of SSH, SFTP and VNC when I need to work with it.

To connect to the Pi, I just need its IP address, which currently is 10.0.1.11. I leave the Pi on all the time, but if I reboot it then the IP address could change since I have not set it up with a fixed IP address. To identify the IP address, I run the utility LanScan (free on the Mac App Store) which shows me all the IP addresses of everything on my local network. The Raspberry Pi is clearly identified.

I can then connect to the Pi via ssh:

ssh pi@10.0.1.11

I’m prompted for the password, which I’ve left at the default (“raspberry”).

If I am only going to be running Xojo console apps, then this is all I need. You really only need to set up VNC if you want to access the Desktop so you can run Xojo desktop apps (or use the Pi UI to run other desktop apps).

Personally I do like using the Pi desktop, so I now need to start the VNC server, which I have previously installed. If you need to install it, easy VNC installation steps are at the official Raspberry Pi site.

At the ssh terminal, I start VNC using its defaults with this command:

vncserver

After typing this command, I’m back at the terminal prompt. Use the “exit” command to disconnect from the ssh connection.

Now I can connect to the Pi using a VNC client. I’m going to use the client that is built into OS X since it is always available and reasonably fast. In Finder, select Go->Connect to Server from the menu. In the window, enter the address and port for the VNC server and click Connect:

vnc://10.0.1.11:5901

You’ll again be prompted for your password. This is the password you set up when you installed TightVNC, not the Raspberry Pi password.

When everything connects you’ll get a window displaying the Raspberry Pi desktop, shown here running the XojoNotes example app:

But how do you get apps to the Pi so you can run them? I use SFTP. There are many SFTP tools available. I primarily use ForkLift and ExpanDrive, but other apps have also been recommended on the Xojo forum. Regardless of the tool you use, create a new SFTP connection and enter the same credentials you used to connect via ssh.

You’ll now have access to the file system on the Pi and you can drag files from your computer to the Pi’s file system, which will copy them across your network to the Pi. With ExpanDrive, I get a drive mounted to the Finder that is connected to the Pi, making access to the Pi always available.

With your free Xojo Pi license you can develop and build desktop and console Pi apps. Download today and get the latest release!