As you probably know, the best way to stay in the “safe zone” when using fonts in your PDF files is to use only the Standard 14 fonts: Helvetica, Times, Courier, Zapf Dingbats and Symbol. As part of the PDF standard, these fonts are as close to a “guarantee” that the operating system will display the text correctly without needing to embed any fonts as part of the PDF file. As result, the PDF files are smaller when you use on the Standard 14.

But, of course, there are times you need to include more visually captivating fonts in your PDF documents. In these cases, you can use fonts that are already available (installed) in the Fonts folder on the OS. But if you want to use fonts that aren’t available by default to the Operating System, PDFDocument has improved in this regard in Xojo 2022r1.

First, the fonts cache manager has been improved for speed, decreasing the time required to access and get the font data even when it’s the first time to be used in text drawing on the PDF document. But not all Operating Systems include the fonts required by the PDF Standard 14, and PDFDocument requires that any font you want to use be installed in the computer/device (or added using AddFonts). Follow these tips:

• macOS includes by default all the fonts required by the PDF Standard 14, except Monterrey. Where Times is not installed you can use Times New Roman.
• Windows doesn’t includes Helvetica, Times, Courier or ZapfDingbats. You can use Arial, Times New Roman, Courier New and install ZapfDingbats or any similar font you want to use.
• Linux doesn’t includes any of the Standard 14 fonts, but you can use some that are equivalent and are installed by default in most of the Linux distributions: Liberation Sans instead of Helvetica, Liberation Serif instead of Times and Liberation Mono instead of Courier. You can install the Symbol and ZapfDingabts font files or any that is equivalent to these.

In addition, it is typical for Linux based servers not to have many fonts installed; make sure to install all the font files you intend to use in the creation of your PDF documents.

Embedding the Fonts in the PDF

On the other hand, and because this was a feature requested by several users, we have brought back the EmbeddedFonts property (set by default to False). This way, when you use any font not included among the Standard 14 ones, the data of that fonts won’t be included either as part of the PDF contents, resulting, thus, in smaller PDF files.

This feature is especially useful for sharing PDFs with people that have the same set of fonts installed in their OSs, as it is the case in many companies. Additionally, using EmbeddedFonts can considerably reduce the size of the PDFs.

But if the PDF documents created this way are distributed for public or general use, then the end user won’t have the exact same set of fonts used during the creation of the PDF and, as result, those not available fonts will be substituted and the text won’t render as expected or was initially designed to (including fonts metrics and styles).

If, on the contrary, the EmbeddedFonts is set to True, then the PDF document will include all the required font information (excluding the data for those in the Standard 14 set) in order to render properly the text, both if the user has those fonts installed or not.

Using Fonts Not Installed in the Operating System

The PDFDocument.AddFonts method has been generally improved and now includes the ability to use fonts not installed when creating PDF Documents in iOS apps created with Xojo.

In this example, I recommend setting the PDFDocument.AddFonts property to True in order to guarantee that the required font data is included as part of the PDF document itself.

Take into consideration the following:

1. While using external fonts on Windows– Provide AddFonts with a FolderItem pointing to the directory containing the font files.
2. While using external fonts on macOS– macOS requires copying to the Resources > Fonts folder, inside the app bundle, for any font you want to use that is not among those available in the Fonts folder. To do this, add a “Copy Files” compilation step to your Xojo project, copying all the fonts you are going to use inside the “Fonts” subdirectory and select “Resources” as the option in the “Destination” entry form the Inspector Panel. In addition, add a text file to the project in the Xojo Navigator (for example named “ExtraKeys.plist”) with the following text:

   <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd"> <plist version="0.9"> <dict> <key>ATSApplicationFontsPath</key> <string>Fonts</string> </dict> </plist>

3. While using external fonts on iOS– As it is the case with macOS, iOS requires copying any fonts you want to use in your PDF and that aren’t already installed to the “App Parent Folder”. To do this, add a “Copy Files” compilation step to your Xojo project, copying all the font files inside the “Fonts” subdirectory, and selecting “App Parent Folder” as the Destination in the associated Inspector Panel. In addition, add a text file to your Xojo project (for example named “iOSKeys.plist”) whose content will be similar to this:

   <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>UIAppFonts</key> <array> <string>Honey.ttf</string> <string>Montserrat-Regular.otf</string> <string>Gypsum.ttf</string> </array> </dict> </plist>Notice how, in this example, the "Honey.ttf", "Montserrat-Regular.otf" and "Gypsum.ttf" entries are the name of the font files that will be added to the iOS app using the Copy Files compilation step. You'll need to change that names for the font files you're going to use (including the file extension) and make sure that the ".plist" file has as many of these entries as the amount of fonts added to the project using the Copy files compilation step.

   

   For example, this screenshot shows a PDF created on iOS that uses the fonts named in the previous “.plist” file.

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

There are a lot of free websites you can use to extract the individual styles and weights from a .ttc file and create .ttf files. But why not do this with Xojo, just for fun … or because I need it! Keep reading and I will show you how.

Extracting the available styles and weights from TTC files requires parsing its data to find the data chunks required to compose the TTF. That is what we are going to do. Start by creating a new Desktop project (you can adapt it later for any supported Xojo targets like Web or Mobile).

Building the TTC to TTF Converter

All the work is going to be done via a method; but because it will be dealing with font files, it would be a good idea to start by creating our own FontUtilities module. So, add a new module to the project and name it “FontUtilities” in the Inspector Panel.

Next, with FontUtilities selected in the Navigator, add a new method to it using the following signature:

• Method Name: ExtractTTFStylesFromTTC
• Parameters: inputFile As FolderItem, outputFolder As FolderItem
• Scope: Public

And add the following code into the associated Code Editor:

#Pragma DisableBackgroundTasks
#Pragma DisableBoundsChecking
#Pragma StackOverflowChecking False

If inputFile = Nil Or Not inputFile.Exists Then Return
If outputFolder = Nil Or Not outputFolder.IsFolder Or Not outputFolder.IsWriteable Then Return

Var mb As MemoryBlock

Var rb As BinaryStream = BinaryStream.Open(inputFile)
mb = rb.Read(inputFile.Length)
mb.LittleEndian = False
rb.Close

If mb <> Nil Then
  
  Var OutputBuffers() As MemoryBlock
  
  // Let's make sure this is a .ttc file by checking the first four bytes of the header
  
  If mb.StringValue(0, 4) <> "ttcf" Then Return
  
  // offset for the total of faces/styles in the ttc file
  Var totalFaces As Integer = mb.UInt32Value(8)
  
  Var tableHeaderOffset As Integer
  Var tableCount As UInt16
  Var headerLength, tLength, tableLength, totalLength, currentOffset As Integer
  
  Var outputBuffer As MemoryBlock
  
  For n As Integer = 0 To totalFaces - 1
    
    // 0x0c is the first possition of the tableHeader offsets
    tableHeaderOffset = mb.UInt32Value(12 + (n * 4))
    
    // offset to the table count from the current table header offset
    tableCount = mb.UInt16Value(tableHeaderOffset+4) 
    
    headerLength = 12 + tableCount * 16
    
    tableLength = 0 
    
    For j As Integer = 0 To tableCount - 1
      
      tLength = mb.UInt32Value(tableHeaderOffset+12+12+(j*16))
      tableLength = tableLength + Bitwise.BitAnd(tLength + 3, Bitwise.OnesComplement(3)) // next value multiple of four
    Next
    
    totalLength = headerLength + tableLength
    
    outputBuffer = New MemoryBlock(totalLength)
    outputBuffer.LittleEndian = False
    
    //Copy table to the buffer for the new file
    outputBuffer.StringValue(0,headerLength - 1) = mb.StringValue(tableHeaderOffset, headerLength - 1)
    
    currentOffset = headerLength
    
    Var tOffset, tOtherLength As Integer
    
    For j As Integer = 0 To tableCount - 1
      tOffset = mb.UInt32Value(tableHeaderOffset + 12 + 8 + (j * 16))
      tOtherLength = mb.UInt32Value(tableHeaderOffset + 12 + 12 + (j * 16))
      outputBuffer.UInt32Value(12 + 8 + (j * 16)) = currentOffset
      
      // Copy data to the buffer for the new file
      outputBuffer.StringValue(currentOffset, tOtherLength - 1) = mb.StringValue(tOffset, tOtherLength - 1)
      
      outputBuffer.UInt32Value(currentOffset) = mb.UInt32Value(tOffset)
      currentOffset = currentOffset + Bitwise.BitAnd(tOtherLength + 3, Bitwise.OnesComplement(3)) // next value multiple of four
    Next
    outputBuffers.Add(outputBuffer)
  Next
  
  // Let's create the .ttf files in the output folder
  Var max As Integer = outputBuffers.Count - 1
  Var outputFile As FolderItem
  
  For n As Integer = 0 To max
    outputFile = outputFolder.Child(inputFile.Name.NthField(".", 1) + " " + n.ToString + ".ttf")
    Var ob As BinaryStream = BinaryStream.Create(outputFile)
    ob.Write(outputBuffers(n))
    ob.Close
  Next
End If

Testing the TTC to TTF Converter

Now, let’s create a minimal user interface in order to test it. Select the Window1 window in the Navigator in order to bring up the Layout Editor. Next, drag a DesktopButton from the Library and drop it inside the window area in the Layout Editor. Use the alignment guides to help you to leave enough room between the button and the window margins.

Double click the button in the Layout Editor to open the Add Event Handler dialog box. The Pressed Event Handler should be selected already, so simply confirm it clicking on the “OK” button.

The Pressed Event Handler has been added under Button1 in the Navigator and with its associated Code Editor visible in the main area, type the following lines of code:

Var inputFontFile As FolderItem = FolderItem.ShowOpenFileDialog(".ttc")
Var outputFolder As FolderItem = FolderItem.ShowSelectFolderDialog

FontUtilities.ExtractTTFStylesFromTTC(inputFontFile, outputFolder)

The first line of code will ask the user to select the “.ttc” font file to process, and the second line will ask for the destination folder where the output (the converted .ttf font files) will be stored. Finally, the third line of code is the one calling our ExtractTFFStylesFromTTC method passing along both the file to process and the output folder.

That’s all! Click on the Run button in the main toolbar of the Xojo IDE. Once the app is running, click on the button to select any “.ttc” file you want to process. Next, the app will ask you to select the output folder and you will be able to see the extracted files inside the selected output folder.

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

As you may know, when you use the System.FontCount and System.FontAt functions on macOS they retrieve the total number of fonts and every style available for the app. Though this is not the case when both functions are used on Windows, there is a simple way for you to retrieve all the fonts and styles available on Windows, including the underlying font file where a particular font style is stored.

Building the WindowsFonts Class

In order to do this, create a new Desktop project on Xojo and add a new Class named WindowsFonts.

Select the WindowsFonts class in the Navigator and add a new Method to it using the following values in the Inspector panel:

• Method Name: Constructor
• Scope: Private

Then add the following snippet of code in the associated Code Editor:

availableFonts = New Dictionary
Var rFonts As New RegistryItem("HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts")

If rFonts <> Nil Then
    Var Max As Integer = rFonts.KeyCount-1
    For n As Integer = 0 To Max
        availableFonts.Value(rFonts.name(n).NthField("(",1).Trim) = rFonts.Value(n)
    Next
End If

Now add the availableFonts property to the class using the following data in the Inspector Panel:

• Property Name: availableFonts
• Type: Dictionary

Next, create the Shared Methods that the class will expose to the user. The first one will be the one responsible of creating the shared instance for the class. Add a new Shared Method and use the following data in the Inspector Panel:

• Method Name: Init
• Scope: Private

Next, enter the following line in the associated Code Editor:

sharedInstance = new WindowsFonts

Now add a second Shared Method to the class using the following data in the Inspector Panel:

• Method Name: fonts
• Return Type: String()
• Scope: Public

Type the following snippet of code in the associated Code Editor:

If sharedInstance = Nil Then init
Var fonts() As String
For Each item As Variant In sharedInstance.availableFonts.Keys
    fonts.add item.StringValue
Next item
Return fonts

The last shared method will be responsible for returning the name of the backing file for a particular font style. Add a third Shared Method using the following data in the Inspector Panel:

• Method Name: FileNameForFont
• Parameters: fontName As String
• Return Type: String
• Scope: Public

And type these two lines of code in the resulting Code Editor:

If sharedInstance = Nil Then Init
If sharedInstance.availableFonts.HasKey(fontName) Then Return sharedInstance.availableFonts.Value(fontName)

The last thing we need to do is add a Shared Property to the class. This property will store a reference to the shared WindowsFont class instance. Add a new Shared Property using the following values in the Inspector Panel:

• Property Name: sharedInstance
• Type: WindowsFonts
• Scope: Protected

That’s all. Now, let’s create a simple user interface to test it.

Testing the WindowsFonts Class

Select the Windows1 window in the Navigator so it is displayed in the Layout Editor. Next, drag a DesktopPopupMenu from the Library and drop it near to the top-left corner of the window in the Layout (use the alignment guides to help you know where to drop it, leaving enough space at the top and left margins of the Window1 window).

With PopupMenu1 selected in the Layout Editor, drag the middle-right resizing handler to make the width enough to display the font names. In addition, change the Name in the associated Inspector Panel to “FontSelector”.

Drag a DesktopLabel from the Library and drop it in the Layout Editor below the FontSelector PopupMenu. Next, change the Text property in the associated Inspector Panel to “Font File:”, and use the resizing handlers in the Layout Editor so it is wide enough to display the text in the label.

Drag a second DesktopLabel from the Library and drop it to the right of the previous one. This is the label we will be using to display the name of the selected font in the PopupMenu. Use the resizing handlers to make it wide enough and change the Text property to an empty string.

The user interface layout should look like the one displayed in this image:

Select the FontSelector item in the Layout Editor and double-click on it in order to display the Add Handler Event Dialog Box. Here we want to select the Opening and SelectionChanged Event Handlers. Once selected, click the “OK” button so these are added to the FontSelector item in the Navigator.

Select the just added Opening Event Handler in the Navigator under FontSelector to access the associated Code Editor and type the following line of code:

Me.AddAllRows WindowsFonts.Fonts

Next, select the SelectionChanged Event Handler entry under FontSelector in the Navigator and type the following line of code:

FontFileLabel.Text = WindowsFonts.FileNameForFont(item.Text)

That’s all. Run the test app, and you’ll see all the fonts, styles and widths of those fonts that are available on your Windows computer. Change the selected entry in the PopupMenu and you’ll see the associated font file name reflected in the label below it.

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.

This technique is more on par with the current Picture.SystemImage you use in your Xojo iOS apps. With it you will be able to set the following attributes:

• Glyph name. You can use Apple’s Symbols SF utility to view all the available symbols and the name associated with each of these.
• Size (in points)
• Weight. The weight of the SF Font, ranging from Ultra-Light to Black. This is an Enumeration value.
• Scale. The scale of the SF Font symbol, ranging from Small to Large. This is an Enumeration value.
• TemplateColor. If you want to tint the resulting glyph, you can provide a ColorGroup parameter (Desktop apps) or a regular Color parameter (Desktop, Console apps).
• FallbackTemplateImage. You can provide a grayscale / black and white image to use as a fallback image, in case there is no way to create a picture from the received “name” string.

As it is the case with the existing iOS method, you will receive a Picture. For example you will be able to use code like this in your desktop projects:

Var c As New ColorGroup(Color.Red, Color.White)
Var p As Picture = SystemImage("highlighter", 120.0, SystemImageWeights.UltraLight, Symbolscale.Small, c, fallback)

IVSFGlyph.Image = p

The “fallback” parameter refers to an image added to a desktop project that will be used if the glyph is not found. This will produce the following glyph, assigned as the image to the ImageView control named IVSFGlyph:

In order to add this kind of functionality to your Xojo Desktop and Console projects on macOS, add a new Module to the Navigator (for example, with the name macOSLib). Then, with the macOSLib item selected in the Navigator, add two enumerations with the following values:

• Name: SymbolScale
• Type: Integer
• Scope: Global
• Values:
  Small = 1
  Medium = 2
  Large = 3

• Name: SystemImageWeights
• Type: Integer
• Values:
  UltraLight = 0
  Thin = 1
  Light = 2
  Regular = 3
  Medium = 4
  Semibold = 5
  Bold = 6
  Heavy = 7
  Black = 8

Now add to the macOSLib module the method that will run both on Desktop and Console macOS apps:

• Method Name: SystemImage
• Parameters: name As String, size As Double, weight As SystemImageWeights = SystemImageWeights.Regular, scale As SymbolScale = SymbolScale.Medium, templateColor As Color, fallbackTemplateImage As Picture = Nil
• Return Type: Picture
• Scope: Global

Click on the cog wheel icon in the Inspector to change to the attributes section for the method, and make sure to set only the options displayed in the following picture:

Finally, put the following code in the Code Editor associated with the newly created method:

#If TargetMacOS

  If System.Version >= "11.0" Then

    If name = "" Then Return Nil

    Declare Function Alloc Lib "Foundation" Selector "alloc" (classRef As Ptr) As Ptr
    Declare Sub AutoRelease Lib "Foundation" Selector "autorelease" (classInstance As Ptr)

    Declare Function NSClassFromString Lib "Foundation" (clsName As CFStringRef) As Ptr
    Declare Function ImageWithSystemSymbolName Lib "AppKit" Selector "imageWithSystemSymbolName:accessibilityDescription:" (imgClass As Ptr, symbolName As CFStringRef, accesibility As CFStringRef) As Ptr
    Declare Function ConfigurationWithPointSize Lib "AppKit" Selector "configurationWithPointSize:weight:scale:" (symbolConfClass As Ptr, size As CGFloat, weight As CGFloat, tscale As SymbolScale) As Ptr
    Declare Function ImageWithSymbolConfiguration Lib "AppKit" Selector "imageWithSymbolConfiguration:" (imgClass As Ptr, config As Ptr) As Ptr
    Declare Function ColorWithRGBA Lib "Foundation" Selector "colorWithRed:green:blue:alpha:" (nscolor As ptr, red As CGFloat, green As CGFloat, blue As CGFloat, alpha As CGFloat) As Ptr
    Declare Sub SetTemplate Lib "AppKit" Selector "setTemplate:" (imageObj As Ptr, value As Boolean)
    Declare Sub LockFocus Lib "AppKit" Selector "lockFocus" (imageObj As Ptr)
    Declare Sub UnlockFocus Lib "AppKit" Selector "unlockFocus" (imageObj As Ptr)
    Declare Sub Set Lib "Foundation" Selector "set" (colorObj As Ptr)
    Declare Sub NSRectFillUsingOperation Lib "AppKit" (rect As NSRect, option As UInteger)

    Declare Function RepresentationUsingType Lib "AppKit" Selector "representationUsingType:properties:" (imageRep As Ptr, type As UInteger, properties As Ptr) As Ptr
    Declare Function InitWithFocusedView Lib "AppKit" Selector "initWithFocusedViewRect:" (imageObj As Ptr, rect As NSRect) As Ptr

    Var nsimage As Ptr = NSClassFromString("NSImage")
    Var orImage As Ptr = ImageWithSystemSymbolName(nsimage, name, "")
    Var symbolConfClass As Ptr = NSClassFromString("NSImageSymbolConfiguration")

    // Getting the weight as the required SystemImageWeight float
    Var tWeight As CGFloat = SystemImageWeight(weight)

    // Creating a configuration obj for the Glyph
    Var symbolConf As Ptr = ConfigurationWithPointSize(symbolConfClass, size, tWeight, scale)

    // Getting the final NSImage from the Glyph + Conf (still in vectorial format)
    Var finalImage As Ptr = ImageWithSymbolConfiguration(orImage, symbolConf)

    // Can't create image from received glyph name, so we return Nil if fallback is not provided
    // or colorize the fallback image if there is one
    If finalImage = Nil Then

      If fallbackTemplateImage = Nil Then Return Nil

      Var fallbackData As MemoryBlock = fallbackTemplateImage.ToData(Picture.Formats.PNG)
      Var fallbackDataPtr As Ptr = fallbackData

      Declare Function DataWithBytesLength Lib "Foundation" Selector "dataWithBytes:length:" (dataClass As Ptr, data As Ptr, length As UInteger) As Ptr

      If fallbackData <> Nil And fallbackData.Size > 0 Then

        Var NSDataClass As Ptr = NSClassFromString("NSData")
        Var NSDataObj As Ptr = DataWithBytesLength(NSDataclass, fallbackDataPtr, fallbackData.Size)

        If NSDataObj <> Nil Then

          Declare Function InitWithData Lib "AppKit" Selector "initWithData:" (imageInstance As Ptr, data As Ptr) As Ptr

          Var NSImageClass As Ptr = NSClassFromString("NSImage")

          finalImage = Alloc(NSImageClass)
          finalImage = InitWithData(finalImage, NSDataObj)

          AutoRelease(NSDataObj)

        End If

      End If

    End If

    If finalImage = Nil Then Return Nil

    Var c As Color
    Var nscolor As Ptr

    LockFocus(finalImage)

    // Applying tint to the image if we receive a valid ColorGroup object

    c = templateColor

    nscolor = NSClassFromString("NSColor")
    Var tColor As Ptr = ColorWithRGBA(nscolor, c.Red/255.0, c.Green/255.0, c.Blue/255.0, 1.0-c.Alpha/255.0)

    // We need to set the Template property of the NSImage to False in order to colorize it.
    SetTemplate(finalImage, False)

    Declare Function ImageSize Lib "AppKit" Selector "size" (imageObjt As Ptr) As NSSize

    Var tRect As NSRect

    tRect.Origin.X = 0
    tRect.Origin.Y = 0
    tRect.RectSize = ImageSize(finalImage)

    Set(tColor)
    NSRectFillUsingOperation(tRect, 3)

    // Getting bitmap image representation in order to extract the data as PNG.

    Var NSBitmapImageRepClass As Ptr = NSClassFromString("NSBitmapImageRep")
    Var NSBitmapImageRepInstance As Ptr = Alloc(NSBitmapImageRepClass)
    Var newRep As Ptr = InitWithFocusedView(NSBitmapImageRepInstance, tRect)

    UnlockFocus(finalImage)

    Var data As Ptr = RepresentationUsingType(newRep, 4, Nil) // 4 = PNG

    AutoRelease(newRep)
    AutoRelease(nscolor)

    // Getting image data to generate the Picture object in the Xojo side

    Declare Function DataLength Lib "Foundation" Selector "length" (obj As Ptr) As Integer
    Declare Sub GetDataBytes Lib "Foundation" Selector "getBytes:length:" (obj As Ptr, buff As ptr, len As Integer)

    // We need to get the length of the raw data…
    Var dlen As Integer = DataLength(data)

    // …in order to create a memoryblock with the right size
    Var mb As New MemoryBlock(dlen)
    Var mbPtr As Ptr = mb

    // And now we can dump the PNG data from the NSDATA objecto to the memoryblock
    GetDataBytes(data, mbPtr, dlen)

    // In order to create a Xojo Picture from it
    Return Picture.FromData(mb)
  End If

#EndIf

As you can see, this method calls the SystemImageWeight method, and also makes use of some Structs. Let’s add to the method that will convert the received enum value to the required CGFloat value needed by the Declare:

• Method Name: SystemImageWeight
• Parameters: weight As SystemImageWeights
• Returned Type: CGFloat
• Scope: Global

Add the following code in the associated Code Editor:

Var tWeight As CGFloat = 0

Select Case weight
Case SystemImageWeights.UltraLight
  tWeight = -1.0
Case SystemImageWeights.Thin
  tWeight = -0.75
Case SystemImageWeights.Light
  tWeight = -0.5
Case SystemImageWeights.Regular
  tWeight = -0.25
Case SystemImageWeights.Medium
  tWeight = 0
Case SystemImageWeights.Semibold
  tWeight = 0.25
Case SystemImageWeights.Bold
  tWeight = 0.5
Case SystemImageWeights.Heavy
  tWeight = 0.75
Case SystemImageWeights.Black
  tWeight = 1
End Select

Return tWeight

And now add three new Structures to the macOSLib module using the following values:

• Structure Name: NSOrigin
• Scope: Global
  X as CGFloat
  Y as CGFloat

• Structure Name: NSSize
• Scope: Global
  Height as CGFloat
  Width as CGFloat

• Structure Name: NSRect
• Scope: Global
  Origin as NSOrigin
  RectSize as NSSize

Add an overloaded method only intended for macOS desktop apps. The main difference is that this one can receive a ColorGroup parameter instead of just a Color object:

• Method Name: SystemImage
• Parameters: name As String, size As Double, weight As SystemImageWeights = SystemImageWeights.Regular, scale As SymbolScale = SymbolScale.Medium, templateColor As ColorGroup = Nil, fallbackTemplateImage As Picture = Nil
• Returned Type: Picture
• Scope: Global

And type the following code in the associated Code Editor for the method:

Var c As Color

If templateColor <> Nil Then
  c = templateColor
End If

Return SystemImage(name, size, weight, scale, c, fallbackTemplateImage)

Click on the cog wheel icon from the method Inspector and set the attributes as shown in the following picture:

Setting SF Glyphs directly to Views

Let’s add now a third method to the module whose main difference is that it will not return a Picture; instead, it will set the specified SF glyph as the image for the received control handler. For example, this is neat if you want to set a SF symbol to a button in you UI interface (among other UI controls).

This is the signature for the new method:

• Name: SystemImage
• Parameters: name As String, size As Double, weight As SystemImageWeights = SystemImageWeights.Regular, scale As SymbolScale = SymbolScale.Small, controlHandler As Integer
• Scope: Global

And the code to put in the associated Code Editor:

#If TargetMacOS

  If System.Version >= "11.0" Then

    If name = "" Then Exit

    Declare Function Alloc Lib "Foundation" Selector "alloc" (classRef As Ptr) As Ptr
    Declare Sub AutoRelease Lib "Foundation" Selector "autorelease" (classInstance As Ptr)

    Declare Function NSClassFromString Lib "Foundation" (clsName As CFStringRef) As Ptr
    Declare Function ImageWithSystemSymbolName Lib "AppKit" Selector "imageWithSystemSymbolName:accessibilityDescription:" (imgClass As Ptr, symbolName As CFStringRef, accesibility As CFStringRef) As Ptr
    Declare Function ConfigurationWithPointSize Lib "AppKit" Selector "configurationWithPointSize:weight:scale:" (symbolConfClass As Ptr, size As CGFloat, weight As CGFloat, scale As SymbolScale) As Ptr
    Declare Function ImageWithSymbolConfiguration Lib "AppKit" Selector "imageWithSymbolConfiguration:" (imgClass As Ptr, config As Ptr) As Ptr

    Var nsimage As Ptr = NSClassFromString("NSImage")
    Var orImage As Ptr = ImageWithSystemSymbolName(nsimage, name,"")
    Var symbolConfClass As Ptr = NSClassFromString("NSImageSymbolConfiguration")

    // Getting the weight as the required SystemImageWeight float
    Var tWeight As CGFloat = SystemImageWeight(weight)

    // Creating a configuration obj for the Glyph
    Var symbolConf As Ptr = ConfigurationWithPointSize(symbolConfClass, size, tWeight, scale)

    // Getting the final NSImage from the Glyph + Conf (still in vectorial format)
    Var finalImage As Ptr = ImageWithSymbolConfiguration(orImage, symbolConf)

    // We need to know if the received Handler can respond to the setImage message (that is, it's a View)

    Declare Function RespondsToSelector Lib "/usr/lib/libobjc.A.dylib" Selector "respondsToSelector:" (obj As Integer, sel As Ptr) As Boolean
    Declare Function NSSelectorFromString Lib "Foundation" (sel As CFStringRef) As Ptr

    Var sel As Ptr = NSSelectorFromString("setImage:")

    // We check if it's a valid handler, we have an NSImage object and the handler can receive the "setImage" message
    If controlHandler <> 0 And finalImage <> Nil And RespondsToSelector(controlHandler, sel) Then

      Declare Sub Set Lib "AppKit" Selector "setImage:" (control As Integer, Image As Ptr)

      // We set the NSImage to the received control
      Set(controlHandler, finalImage)

    End If

  End If

#EndIf

So, for example, you can set now the Gear symbol as the image of a PushButton control added to the app UI using the following code in the Open Event Handler of the PushButton instance:

SystemImage("gearshape.2", 14.0, SystemImageWeights.Regular, SymbolScale.Small, Me.Handle)

Summary

And that’s all! As you can see, there are no hardcoded codepoints for the SF glyphs. You’ll be able to create a picture from any SF symbol at the desired points size, weight and scale. Plus, you’ll be able to colorize it and receive a fallback image if anything goes wrong in the process.

You can download the example Xojo project with the Module already created from this link.

After the publication of Quick Tip: SystemImage, more than 2,400 symbols at your disposal, a user asked how to do the same on macOS. Continue reading to learn one way or check out QuickTip: Using SF Symbols in macOS … revisited! for a more flexible way to work with SF Symbols on macOS 11+.

The first step is to install the SF Pro font; download it from this link and use the Font Book app to move it to your System fonts folder. In addition, you’ll find the SF Symbols utility valuable. It shows you the glyphs for the symbols in each font and the associated names.

On macOS we don’t have the Picture.SystemImage method to get and display these symbols, so what do we use? Well, they are simply glyphs from a font which means that we can get the Unicode codepoint for the symbols and use them in combination with the shared method Encodings.utf8.chr. The main problem is finding an easy way to get the codepoint equivalence for every symbol name found in the SF Symbols utility. To make this easier for everyone, download this Xojo example project of a very basic class that does this for you. You’ll need to use the method SFSymbol.Name to provide the available names to get the String including the glyph.

In order for your app layout Controls to properly display the symbol you’ll also need to set the FontName for the control, for example, “SF Pro Display” or “SF Pro Compact”,  as well as set the FontSize property to the expected symbol size. You can use these symbols as the caption for buttons, the text drawn in any canvas or for any other item. In the image above you can see the SF Symbols applied to two standard Xojo buttons and also to the first column of the ListBox (displaying the associated Symbol name in the second column).

Using these symbols, as you already do with any of the other fonts, guarantees the maximum quality and sharpness at any size you choose. In addition, these also will react properly to Light Mode and Dark Mode.

Of course, you can make use of the SF Pro font in your apps under the license agreement and restrictions provided by Apple. In addition, macOS 11 includes a new API that is equivalent to the one found on iOS … I’ll show you how to use it in a future post.

Bonus!

Maybe you want to use these symbols as the icon displayed in the available Xojo buttons but you want to display them in different colors. There is a way to do it through declares! Take a look at the ColorForButtonCaption method under the SymbolList window.

Questions? Ask me on Twitter @XojoES or on the Xojo Forum.

You can find fonts on websites like iosfonts.com. But wouldn’t it be great to access these directly from code? Let’s learn how your iOS app can offer the user the option to select the font they want from a list (or any other UI control of your choice) just like in Desktop apps.

To do this, use a little helper class included in the iOS example project (download from this link). This class uses the Singleton pattern, and if a font is not installed on the iOS version of the device running the app, then it fallbacks to the default font used in iOS.

With this class at hand, you only need to call the shared method:

iOSSystemFonts.Fonts As String()

In order to receive an Array of Strings containing the name of the fonts. The class also provides the following shared methods:

iOSSystemFonts.FontCount As Integer

iOSSystemFonts.LastFontIndex As Integer

iOSSystemFonts.FontAt(Index As Integer, Optional size As Integer = 0) As Font

To try this out for yourself, download and run the sample project.

Questions? Ask me on Twitter @XojoES or on the Xojo Forum.

In order to simplify their use, we included an Enumeration as part of the PDFDocument Class. So, if for example you want to use the Times-Bold variant, then you only need to use these two lines of code:

g.FontName = PDFDocument.StandardFontNames.Times
g.Bold = True

This also speeds up the creation of your PDFs – Bonus!

Beyond the Standard 14

But you may need something beyond the standard 14 and that is where things can start to get more complicated. In order to be able to “draw” these other fonts in vectorial representation as part of your document, the PDF standard needs to know in advance lots of details of the typography itself: glyphs width, maximum and minimum kerning values, if they include Italic or Bold variations, etc. And it can get even more complicated when you need to support several fonts. That means that the PDFDocument class needs to go inside and explore every one of the fonts you may use in your document so they are properly rendered, and that means inspecting a LOT of data!

In oder to alleviate this very consuming process, the PDFDocument class uses several techniques to speed things up when it comes to the many fonts you have installed. For example, one of the more obvious of these is using a delayed font exploration … so it only takes place when you are going to use a specific font the first time, caching all the required information for later accesses. In addition, it pre-caches the name of all the fonts you have installed in your OS Fonts folder so it can “find” those fonts faster once you’re ready to use one of them.

These two techniques, in addition to others, ensure that the initial PDFDocument creation and text drawing is as fast as possible for the “reasonable” (or even for the not so “reasonable”) amount of fonts you may have installed in your computer.

An important difference when using fonts other than the standard 14, is that nobody ensures that the user viewing your PDF document will have that same fonts installed on their computer too (including even variants of the same font) and that can lead to a rendering text “disaster”!

In order to guarantee that your PDF texts will render correctly, no matter how many fonts you are using, all the required font data is included as part of the PDF document itself (it has embedded the font data). For the small price of including the font data as part of the document, regardless of if the user has any of the fonts installed on their computer, the text of the PDF document will be rendered however you set it during its creation.

No matter how many times you are going to use the same font in your document, the reference (and, thus, the font data) will be included only once.

Speeding Things Up

In addition, it may be the case that you are interested in working only with a subset of the fonts you have installed on your drive (or apart from these, for example, only the ones included as part of your own app or solution). If that is the case, then you can use the PDFDocument.AddFonts method passing along a FolderItem parameter pointing to the folder containing the font files. Just make sure to use this method before using any of the fonts! Also, this will speed up the font inspection process even more because the PDF will look for the required data only among the files added by the AddFonts method. You may use the PDFDocument.AddFonts pointing to different font sets as many times as you may need.

For example, let’s say we have a folder on the desktop with a total of 20 font files inside; so the following snippet of code will create a “Font catalog” PDF document whose contents are a total of 20 lines composed with a fixed sample text followed by the font name:

Var f As FolderItem = SpecialFolder.Desktop.Child("Fonts Catalog")

PDFDocument.AddFonts(f)

Var fName As String
Var pdfDoc As New PDFDocument
Var g As Graphics = pdfDoc.Graphics
Var offset As Integer = 20

Var textSample As String = "Text Sample with Font: "

For n As Integer = 0 To 20
  
  fName = f.ChildAt(n).Name.NthField(".", 1)
  
  g.FontName = fName
  g.FontSize = 10
  g.DrawText(textSample + fName, 20, offset)
  
  offset = offset + 10 + g.FontAscent
  
Next

Var target As FolderItem = SpecialFolder.Desktop.Child("FontSample.pdf")

pdfDoc.Save(target)

target.Open

In this case, the following screenshot shows the resulting PDF document:

The total size of the PDF document is a mere 700 KB on disk, with the guarantee that it will be correctly displayed by anyone you send it because the font data is embedded in the document itself! If you are curious, you can download the PDF document itself from this link.

The font is called JetBrains Mono (from JetBrains, makers of a Java IDE). Be sure to check out the web site as it shows off many of the cool features of the font:

https://www.jetbrains.com/lp/mono/

Above you can see how the Xojo IDE Code Editor looks with this font. I’ve only just started using it but so far I find it a bit easier to read than Source Code Pro, which is what I have been using.

You can see what is available for Google Fonts here:

https://fonts.google.com

Here are the steps to use a Google Font in your web app.

1. Click on the name of the font to go to its page. As an example font to try, select the font called “Orbitron”.
2. On the Orbitron page, click “SELECT THIS FONT” in the top right.
3. This adds a banner at the bottom of the page that says “1 Family Selected”. Click the banner to display the full details. Make sure “Standard” is selected and copy the HTML text. For Orbitron it looks like this:

   1. <link href="https://fonts.googleapis.com/css?family=Orbitron" rel="stylesheet">

4. In your Xojo web project select the App and then click the “pencil” icon next to the HTMLHeader property to show the editor. Paste the text you copied from above into the property. Leave the editor open as you have more HTML to add.
5. Go back to the Orbitron page and copy the text in the “Specify in CSS” section. For Orbitron it looks like this:

   1. font-family: 'Orbitron', sans-serif;

6. Back in Xojo, add <style></style> tags to the editor.
7. In between the style tags, add a period followed by the name of the Google Font and two curly brackets

   1. <style>.Orbitron {}</style>

8. In between the curly brackets add the code you copied from above.
9. In the end you’ll have text in the editor that looks like this:

   1. <link href="https://fonts.googleapis.com/css?family=Orbitron" rel="stylesheet">

   2. <style>.Orbitron {font-family: 'Orbitron', sans-serif;}</style>

10. Go back to Xojo can create a new Web Style. Make sure its name matches the name of the Google Font This is case-sensitive so make sure it matches exactly. For Orbitron, the Web Style should be called “Orbitron”.
11. On WebPage1, add a Label with some text and change its Style property to Orbitron.
12. Run your project. The text should appear using the Google Font.

Special thanks to Michel Bujardet, Matthew Combatti and others for pointing out this technique in these forum conversations: Google Fonts, CSS Styles.

References: Xojo Dev Center, Google Fonts, Xojo Forum

Monaco
This font is installed by default on MacOS. It is big and very easy to read.
http://www.gringod.com/2006/11/01/new-version-of-monaco-font/

Menlo
Also included by default on MacOS.
http://en.wikipedia.org/wiki/Menlo_(typeface)

Source Code Pro
Adobe just released this font in 2012 or so and I really like it. I have been using as my default font since I first found out about it. The screen shot below shows how it looks in Xojo on Mac.

https://github.com/adobe-fonts/source-code-pro

Inconsolata
This is what I used until I switched to Source Code Pro. It is a little smaller than other fonts at the same point size.
http://levien.com/type/myfonts/inconsolata.html

ProFont
This is the first alternative font I used. I think the others mentioned here are nicer.
http://www.tobias-jung.de/seekingprofont/

What do you use?
There are dozens of other great programming fonts. What is your favorite? Let us know on Twitter (@xojo).
Note: A version of this post was previously published in Oct 2012.