A heatmap is a grid of fields that can have different sizes and colors. Heatmaps are often used to analyze website user behavior. Each area is assigned a color, and heat maps let you see the high and the low of that area. They often look like the image of a thermal camera, which is where the name comes from. Of course, a heatmap can also be used for displaying different temperatures, as its name so aptly describes. In this example we want to do that. We have the monthly mean temperature for a city for the last 10 years and we want to display this temperature by colors in a heatmap. 

The Data

To do this, we first create an array in which we write the years we have and an array with the individual month names: The information in these arrays will be needed later for the labelling of the axes. 

In order to be able to display values in a diagram, we want to write the values into a single array with all the months following with their values. We will combine the values as follow: 

Array( Jan ( 0 ) … Jan ( 9 ) , Feb ( 0 ) … Feb ( 9 ) , Mar ( 0 ) … , … Dec ( 9 ) )

We start with the January values and append the other months behind it. We can highlight special parts of the heatmap by adding a star, a polygon or a cross of any color to the area. 

Creating the Heatmap

Now we come to the creation of the actual diagram. We create an area 600 x 500 pixels in size; on this area we will later draw our chart and the legend. To do this, we create an instance of the class CDXYChartMBS and pass the size in the parameters. 

Dim c As New CDXYChartMBS(600, 500)

Above the chart, with addTitle, we can add a title that describes our chart. Our chart should be on an area of 400 x 400 pixels and have a distance of 80 pixels from the top edge. The background color, as well as the grid color is transparent. 

Dim p As CDPlotAreaMBS = c.setPlotArea(80, 80, 400, 400, -1, -1, CDBaseChartMBS.kTransparent, CDBaseChartMBS.kTransparent)

Now our symbol for minimum temperature is added. The minimum temperature is a small circle in a light blue color. In the addScatterLayer method we first specify the X and Y coordinate arrays as parameters then the title that will later be displayed in the legend next to the diagram and the shape of the symbol. Here we use PolygonShape. The number in the brackets behind the shape indicates the number of sides of the polygon. If this is 0, we see a circle. Then in the parameters follows the size of the symbol and the color. The structure is the same for other marks.

Call c.addScatterLayer(symbolX, symbolY, "Min value", CDBaseChartMBS.PolygonShape(0), 15, &hc6e2ff)

Now we create the heatmap with the method addDiscreteHeatMapLayer. It should have a size of 10 x 12 cells. 10 cells on the x axis and 12 cells on the y axis. In the parameters we first specify the array with the data and then the amount of cells on the x axis. For this we have to determined the array size of the array of the years. The cell amount for y axis is automatically determined from the amount of data. 

Dim layer As CDDiscreteHeatMapLayerMBS = c.addDiscreteHeatMapLayer(zData, xLabels_size)

We now set the labels for the axes. With the method setLabels we specify the text. With the method xAxis.setLabelStyle we specify the font and the font color. The label should be rotated by 90 degrees on the x axis so that it is easier to read. With setLabelOffset we set the distance of the text to the grid border. With a value of 0, the text would be on the left or upper edges of the cell and not in the middle. With setXAxisOnTop we indicate that the text of the x axis should be above the diagram. 

The setting of the y axis labels is similar

Call c.xAxis.setLabels(xLabels) 
Call c.xAxis.setLabelStyle("Arial Bold", 10, CDBaseChartMBS.kTextColor, 90) c.xAxis.setColors(CDBaseChartMBS.kTransparent, CDBaseChartMBS.kTextColor) 
c.xAxis.setLabelOffset(0.25) 
c.setXAxisOnTop 

Call c.yAxis.setLabels(yLabels) 
Call c.yAxis.setLabelStyle("Arial Bold", 10) c.yAxis.setColors(CDBaseChartMBS.kTransparent, CDBaseChartMBS.kTextColor) 
c.yAxis.setLabelOffset(0.25) 
c.yAxis.setReverse

Now we want to specify the individual colors for the value ranges. For this we create a new array. In this array we first enter the lower limit of the temperature that the color should describe, then the color value in hexadecimal followed by the uppermost value. The uppermost value is at the same time the lowermost value of the next color, so we don’t enter it twice, but give directly the next color. Our values all have a distance of 3 degrees. Afterwards we create the array colorLabels, which describes the text for our legend

Dim colorScale() As Double = Array(0.0, &h104E8B, 0.0, &h00BFFF, 3.0, &h7FFFD4, 6.0, &hFFFF00, 9.0, &hFFC125, 12.00, &hFF7F00, 15.00, &hff4500, 18.00, &hcd0000, 21.00,&h8B0000, 21.10) 
Dim colorLabels() As String = Array("<0.0", "0.0-3.0", "3.1-6.0", "6.1-9.0", "9.1-12.0", "12.1-15.0", "15.1-18.0", "18.1-21.0", „>21.0“)

We then apply the colors with colorAxis.setColorScale on the layer level.

layer.colorAxis.setColorScale(colorScale)

We place the legend 20 pixels to the right of the diagram. We use the font Arial Bold in size 10. With setKeySize we set the size of the legend boxes and with setKeySpacing the vertical distance between the individual legend entries.

Dim b As CDLegendBoxMBS = c.addLegend(p.getRightX + 20, p.getTopY, True, "Arial Bold", 10) 
b.setBackground(CDBaseChartMBS.kTransparent, CDBaseChartMBS.kTransparent) 
b.setKeySize(15, 15) 
b.setKeySpacing(0, 8) 
b.addText("Temp in °C“)

For the colors we use a trick, we read only the colors from the array that contains the color values and the temperature ranges by looking only at every second value. With the method addKey we then add the tag with the name and the extracted color. 

For i As Integer = colorLabels_size - 1 DownTo 0 
 Dim n As Integer = colorScale(i * 2 + 1) 
 b.addKey(colorLabels(i), n) 
Next

With the method makeChartPicture we get our diagram as picture:

pic = c.makeChartPicture

And you can show this picture as backdrop to better draw it with the paint event. If you use MakeChart with PDF type as parameter, you can get a PDF file to embed in a PDF page as vector graphics.

Then we can run the program and see our heatmap. You can then continue to work with this heatmap according to your own preferences. The final heat map looks like this:

As I mentioned at the beginning of this post, you’ll need the MBS Xojo ChartDirector Plugin which you can purchase on the MonkeyBread Software website; or, at the moment, it’s included in super the Omegabundle deal. Besides ChartDirector, Omegabundle includes a ton of other tools for the sensational price of 399.99$. For example, you also get a DynaPDF Starter license with which you can use to write the chart into a PDF file. If you want to attend the Xojo Developer Conference 2022 in London and meet us, Omegabundle includes a discount of 100$ for the conference! Read articles from the Xdev developer magazine on the way to the conference, because it’s also included in the bundle! Have a look at the Omegabundle. It’s worth it. I hope you enjoy the heatmap!

Stefanie Juchmes studies computer science at the University of Bonn. She came in touch with Xojo due to the work of her brother-in-law and got a junior developer position in early 2019 at Monkeybread Software. You may have also read her articles in Xojo Developer Magazine. 

Developer Tools

piDog DataView is a fast and flexible list viewer and includes one year of updates.

Markdown Parser for Xojo is a class that allows you to implement the ability to parse Markdown source text into HTML + the provided CSS styles, so it can be presented on the fly over an HTML control for its use “as-is”, as a starting point for invoices, reports, templates or document conversion.

If you don’t have anything from Monkeybread Software, then this is a great deal for you! Everything is 20% off from the Complete Plugin Set, which includes 54,000+ functions, to DynaPDF for creating and editing PDF documents and more.

Mime Parser is a class for parsing emails.

The OMP Plugin allows you to easily parse Microsoft Outlook Structured Storage (.MSG) files cross-platform from Xojo.

Also offered is a Spell Checker Class to easily spell check text.

User Interface

ARWaitingView is a class to prevent the user from navigating the interface while something is downloading or doing a long process.

AXControlGrid is a complete and powerful Xojo desktop UI component for macOS and Windows that it makes possible to put Canvas-based controls in a Page or a series of Pages of a given size and, optionally, their associated captions.

AXImageCanvas greatly simplifies the task of displaying a Picture with the ability to correctly display the image maintaining its original aspect ratio, and keeping the full resolution of the picture and reference to the original FolderItem.

AXNumValidatedTF is a Xojo TextField subclass (32/64 bits) for Windows and macOS allowing the input validation of a defined numeric range, using the system Locale settings for decimal and grouping text formatting.

Antonio Rinaldi offers Doughnut, which is an extension for iOSGraphics to draw circular graphs. Additionally, iOSTableViewExtended is a subclass that adds useful features including: swipe to reload, table header and footer, customer section header and footer, contextual menus, side index, TextEdit fix and more.

GraffitiSuite All Access, Desktop and Web are on sale! They are a collection of custom components for Xojo Desktop and Web.

MBS ChartDirector lets you create professional charts in Xojo, with 30 chart and gauge types.

RubberViews from Match Software maintains the place and relative size of every control when a Window or Container Control is resized. They also offer Window Placement and Screen Extensions that are modules that let you manage windows with greater control.

Database

DataViewer Component is a collection of objects for Xojo that can easily incorporate into your own projects to give SQL Query and DML functionality for SQLite and MySQL databases along with Data Export facilities. Full source code edition also available.

The MBS SQL Plugin is an alternative database interface to Xojo that gives access to SQL databases including Oracle, Microsoft SQL Server, DB2, Sybase, Informix, InterBase/Firebird, SQLBase, MySQL, PostgreSQL, ODBC and SQLite. Also available is the MBS SQLite Extension is a plug-in for cubeSQL Server, a plug-in for SQLite Manager (sqlabs) and an extension for SQLite that you can use in all SQLite-based database engines, including the SQLiteDatabase class in Xojo.

SQLVue is the fast and easy way to manage your SQLite databases.

Distribution

App Wrapper from Ohanaware simplified the process of preparing applications for submission to the Mac App Store and deploying on websites. Get a 30-day or a 1 year single user or team update plan during this limited time offer.

BoxedApp Packer helps Xojo developers prepare a single executable file that contains all required files a Xojo application needs.

The GuancheMOS plug-in is a serial number creation and validation Engine. Also available is GuancheID, the easiest way to get a unique ID for macOS and Windows based computers, so you can use it in combination with GuancheMOS or your own software licensing scheme to make sure your software only runs on the computer the license has been generated for.

Quick License Manager protects your Xojo Windows application with licensing for trials, perpetual or subscription-based licenses.

Learning

AprendeXojo has 2 Spanish-language ebooks in the store available for $20 each during the sale: Programación Multiplataforma Xojo and SQLite.

xDev Magazine is an independent bimonthly publication focused on educating Xojo users through instruction, tutorials and programming. Score a 1 year subscription during the sale for just $40!

Shop Now

The Xojo Extras store has something for every kind of Xojo developer, whether you are learning something new or looking to save some time implementing something tricky. Take a look now to see what can help make your development life easier! The Xojo May Sale runs until midnight (CT) Friday, May 7th.

In this example we create a pie chart. A pie chart has one-dimensional data, that means that we need to filled one array with data. Here is our example: 

Imagine a bakery making $1,500 a day. We now want to read from our chart what percentage of the profit is made by bread, buns, cakes and cookies. For this we enter in our array the 600$ of bread, 335$ of buns, 309$ of cake and 256$ of cookies. 

So our array definition looks like this: 

Dim data(-1) As Double = Array (600, 335, 309, 256)

We don’t have to worry about the percentage, because it is automatically calculated based on the specified array. 

Now we create another array with the corresponding labels. It must be ensured that the label sequence corresponds to the order of the data sequence. 

Dim labels(-1) As String = Array (“Bread”, “Buns”, “Cake”, “Cookies”)

We also arrange the colors of the individual circle sections as an array. Here is a small tip: You can use already known color combinations, lists of color combinations that harmonize well with each other can be found in the Internet in large numbers. 

I have chosen a combination of pink and purple tones: 

Dim colors(-1) As Integer
colors.Append &hBB397A
colors.Append &h7B448D
colors.Append &hDE69A5
colors.Append &h9672c6

Then we create our diagram working environment. 

Dim c As New CDPieChartMBS(600, 400, &hffffff, &hffffff, 0)

In the parameters we can set the height and width of the working environment, the background color, the edge color and the stars of the elevation effect. 

In the image you can see a working environment with a red background, blue edge color and the elevation of 5, additionally the corners have been rounded with the method setRoundedFrame.

But for our example we take a white background.

Then we can insert the title of the diagram that should appear in the middle of the upper side. In the parameters we can set the text, font, font size, font color, font box background color and the text box border color. In our example we define only the text and leave the remaining parameters at the default values.

call c.addTitle(“Pie Chart Demonstration”) 

Now we can make some settings for the chart.

First we define the size and position of the pie chart. 

c.setPieSize(300, 200, 110)

Our working area has a size of 600×400 which means that if we want to position the chart in the middle of our working area we have to halve these values so we get 300 and 200 which we then specify in the parameters. The third parameter describes the size of the pie chart with the radius. If we had a ring chart instead of a pie chart, the inner radius would be given in a fourth parameter and the called function would be setDonutSize. 

Afterwards we can specify the color of the data areas. 

In the first parameter we specify that we want to set the data color, because the SetColors method can be used in many more areas. In the second parameter we specify the already created array colors :

c.setColors(c.kDataColor, colors)

Then we can set that our pie chart should be shown as a 3D figure and with the command: 

c.set3D(deeps, 45, False)

Set the heights of the segments so that they look like stairs and the angle with which we look at the chart. The point of view depends on the shadow mode, which is switch off by default. 

With Shadow Mode (2) and without Shadow Mode (3)

We prefer that the angle of the first segment does not start straight up, for this we use the SetStartAngle method. Also, the individual segments should not stick to each other and there should be a small gap between them. We want to highlight the largest segment a bit more and move it further out. In the SetExplode method we first specify the data segment we want to push out of the circle and the amount by which it should be pushed out:

c.setStartAngle(-20)
c.setExplode(0, 20)
c.setExplode(1, 20)
c.setExplode(2, 2)
c.setExplode(3, 2)

So that our data can also be displayed we have to pass the data to the diagram. With SetData we specify the data and assign the right labels to them. Both informations we find in the already prepared arrays:

c.setData(data, labels)

Our labels do not look handsome yet. We would like to change that now by defining their style. The label name should be italic, bold and a little bit bigger, than the other labels. Underneath it should be the given value in US$ and in brackets behind it the percentage value

The definition of this style is as given here in a format string:

c.setLabelFormat(“<*block,halign=left*><*font=timesbi.ttf,size=12,underline=0*>{label}<*/font*><*br*>US$ {value} ({percent}%)”) 

In the style sting we first define the text alignment. This should be left-aligned. Then we specify timerbi.ttf as font. This font is already italics and bold (recognizable by the b and i at the end). In addition, we specify the font size with 12 and that the text is not underlined. These specifications refer to the label text. This is specified with {label} in the style string. After a line break the text US$ and the value of the segment that is specified with {value} is following. In the default case it is assumed that the value is a number. But if it is a date we can format it with the following additions: {value|mm/dd/yyyyy}, {value|mm/yyyyy} or {value|yyyyy}. In our example, the percentage with {percent} in brackets follows.

If you want your segment description texts to be highlighted in the individual segment colors and have lines to the individual segments, you can add the following line:

c.setLabelLayout(c.kSideLayout)

Finally, we want to display our diagram in the window as a background picture. To do this, we adjust our window size to the size of the diagram. Then we create a picture with the method makeChartPicture, which we then set as the backdrop. 

w.Height = c.getHeight
w.Width = c.getWidth
w.Backdrop = c.makeChartPicture

Of course we could have used the picture also to write it into a file. For this we can use the method Save in combination with a folder item or we could have used the picture to insert it into a PDF file with DynaPDF. 

There are many more possibilities to design charts with Chart Director, but this example should give you a short insight to the work with Chart Director. 

To use these functionalities you need a license of the MBS ChartDirector Plugin. You get it either in the Xojo store, on our website or currently in the OmegaBundle 2020.

I wish you a lot of fun with the charts in Xojo. Download the project.

Stefanie Juchmes studies computer science at the University of Bonn. She came in touch with Xojo due to the work of her brother-in-law and got a junior developer position in early 2019 at Monkeybread Software. You may have also read her articles in Xojo Developer Magazine. 

The SAP interface has four steps:

1. Determine the path to the SAP library 
2. Build a connection to the SAP system
3. Transfer data to the SAP system
4. Receive data from the SAP system

Connect the SAP System

Your SAP user must have the authority for RFC connections. If so, you must know some data of your SAP logon to connect to an SAP system, such as:

• host name – a name or an IP address (ashost)
• router string 
• system number (sysnr)
• client (client)
• language (lang)
• user (user)
• password (passwd)

At first you must set the path to the SAP libraries. In Windows you have some DLL’s around SAPNWRFC.DLL and on macOS you have some DYLIB’s around LIBSAPNWRFC.DYLIB.

If TargetWin32
  var LibFile as string = "sapnwrfc.dll"
Else
  // get the actual folder and handle the exception
  var MacOsFolder as folderitem = app.ExecutableFile.Parent
  System.EnvironmentVariable("DYLD_LIBRARY_PATH") = MacOsFolder.NativePath
  If System.EnvironmentVariable("DYLD_LIBRARY_PATH") = "" Then
    MessageBox("DYLD_LIBRARY_PATH variable not set")
    return
  end if
  var LibFile as FolderItem = MacOsFolder.Child("libsapnwrfc.dylib")
  var LibPath As String = LibFile.parent.NativePath
  Call RFCModuleMBS.SetCurrentWorkingDirectory(libPath)
EndIf

I’ve copied the SAP libraries with the Xojo build settings into the application resource folders. 

If the setting of the LibPath fails then send the error message:

If not RFCModuleMBS.LoadLibrary(LibFile) Then
  // Failed to load library
  Messagebox RFCModuleMBS.LibraryLoadErrorMessage
  return
End If 

And if the LibPath is set you can do the logon as second step:

var loginParams As New Dictionary
loginParams.Value("ashost") = "12.345.67.89"
loginParams.Value("sysnr")  = "10"
loginParams.Value("client") = "100"
loginParams.Value("user")   = "MYUSERNAME”
loginParams.Value("passwd") = "MyPassword"
loginParams.Value("lang")   = "EN"
var ConnectionToSAP As New RFCConnectionMBS(loginParams) 

Please note if you have a router string you must build the host name (ashost) with a concatenation of router string and host name like this:

loginParams.Value("ashost") = <router string> + "/H/" + <host name>

If the connection fails you will get the reason with:

Exception r As RFCErrorExceptionMBS
 MessageBox r.message 

Calling an SAP Function Module

If you are calling a SAP Function Module you will export key values to SAP and you will receive data or i.e. error messages. To understand the import and export parameters you must look out of the SAP function module in the surrounding world.

This example calls the SAP function module RFC_READ_TABLE. With this standard RFC module you can get the content of a database table and/or the SAP data dictionary description of this table.

Exporting key values to SAP

For exporting the key values to the SAP function module you must load a functions description and create a data container for executing the function module.

var fd as RFCFunctionDescriptionMBS = app.ConnectionToSAP.FunctionDescription("RFC_READ_TABLE")
var f as RFCFunctionMBS = fd.CreateFunction 

The function module RFC_READ_TABLE has two parameters:

• the name of the table as import parameter: QUERY_TABLE
• the select options of the where clause as tables parameter: OPTIONS

f.StringValue("QUERY_TABLE") = "<name of the table>"

var it_OPTIONS as RFCTableMBS = f.TableValue("OPTIONS")
var is_OPTIONS as RFCStructureMBS

is_OPTIONS = it_OPTIONS.AppendNewRow
is_OPTIONS.StringValue("TEXT") = "(MATNR = '4711')" // WHERE clause

You must consider that the maximum length of a where clause for the table OPTIONS is 72 digits. If the where clause length is greater than 72 you must split the clause to several lines. The clause must look like this “(MATNR = ‘1234’ AND WERKS = ‘1000’) OR (MATNR = ‘3456’ AND WERKS = ‘1000’)”. 

And now you can execute the function module into the backend system:

f.invoke

Receiving data from SAP

The function module RFC_READ_TABLE returns now to tables parameters:

• FIELDS – contains the SAP data dictionary description of the returned table
• DATA – contains the data found for the transferred where clauses

TableFields as RFCTableMBS = f.TableValue("FIELDS")
TableData as RFCTableMBS = f.TableValue("DATA") 

If the TableFields.RowCount = 0 then the returned table contains no data. To get the content of a returned table you must loop like this:

If TableData.RowCount > 0 then
  TableData.MoveToFirstRow
End if
For iRow as integer = 1 to TableData.RowCount
  // get a field value
  Var FieldValue as string = TableData.StringValue("<Fieldname in the table record>")
  If iRow < TableData.RowCount then
    TabeData.MoveToNextRow
  End if
next

Error Handling

To catch an exception, you should code into your method something like this:

 Exception r As RFCErrorExceptionMBS
  MessageBox r.message 

Interpretation of Returned Data

If you want to get after the INVOKE the returned data you will have 

• a table or
• a structure or
• a field

If you have a table you will get a certain field with:

Var TableContent as RFCTableMBS
TableContent = f.TableValue("<Name of the returned table parameters>")
If TableContent.RowCount > 0 then
  TableContent.MoveToFirstRow
End if
For iRow as integer = 1 to TableContent.RowCount
  ListBox1.AddRow(TableContent.StringValue("FieldOne"), TableContent.StringValue("FieldTwo"))
  If iRow < TableContent.RowCount then
    TableContent.MoveToNextRow
  End if
Next

If you have a structure you will get a certain field with:

var s As RFCStructureMBS = f.StructureValue("ES_MESSAGE")

TextField1.Value = s.StringValue("FieldOne")

If you have a field you will get the data with:

TextField1.Value = f.StringValue("FieldName")

Using the above techniques with the MBS plugin, your Xojo apps can now access information contained in SAP.

Michael Eckert studied economics from 1982-1986 and has been employed at T-Systems as a software architect since 1989. Michael has worked with ERP systems for 34 years, until 1998 with PL/1, since 1998 with ABAP in SAP R/3 and SAP S/4 HANA. He’s been developing with Xojo for about 9 years.

Things like drag and drop (from other sources and also to other sources), undoing the picture assigned, moving the control instances around the parent RectControl (or Window), reacting to DarkMode changes on macOS, and properly resizing the picture so it fits in the Canvas area while keeping its original aspect ratio are implemented in AXImageCanvas, among other features.

Of course, AXImageCanvas abstracts the user from everything related to the usual CRUD operations associated with a Database backend: Creating a new Record, Retrieving the Picture from a record, Updating the Picture of an existing record, and Deleting the Picture for the designated record. All of this trying to mimic the easiness of use we are used to when using the standard Xojo framework itself.

The user only needs to assign, paste or drop the Picture to display … and AXImageCanvas takes care of the rest.

So, for example, the binding behavior to a database is implemented in a way that tries to emulate one of the most appreciated features for Xojo users in the past: DataControl.

The user only needs to set the database instance they want to use (it may be a MySQL/MariaDB, PostgreSQL or SQLite database instance), the name of the table they want to use, the name of the column to store the pictures and (optionally) the name of the column to store the original path to a picture read from a FolderItem.

Even if there is only set the column to store the original Picture FolderItem path, then it will not save the Picture data itself, and it will recover the picture later to display based on the saved path information. This alleviates the database data overload for some use cases, when the developer of a solution prefers not to store the picture data in the database itself, just the path pointing to it.

The class is also smart enough to abstract the user from all the SQL queries it would have to write in function of the database engine used. It is completely transparent, as it is the navigation through the database records even if their IDs are not consecutive (this is a mandatory requirement: the table has to have an ID column).

The logic put in the class also gathers information about the database table itself, if for example it only has the two columns set to the instance (Picture column and Picture source path column; plus the mandatory ID column), then the Delete Record action will effectively delete the record from the assigned database table; otherwise, if the table has more columns, it will NOT delete the record, because it’s something you probably wouldn’t want to do … and it simply updates the displayed record to empty (nullify) the information for the Picture and (optionally) the Picture Path columns, keeping thus the rest of the record data intact.

As for PostgreSQL database, there are two paths that can be taken regarding storing Pictures. We can say that the first one is the usual path, storing the Picture data itself in a column table (valid for data not exceeding 1 GB) and through Large Objects (pg_largeobject) via the previous acquisition of an OID value. AXImageCanvas uses the first technique.

In addition, it also properly deals with record navigation for all the supported databases engines even if the records IDs are not consecutive; and when the records navigation is set to the “wrap around” mode, it does it also correctly for all of the supported databases engines.

Another common quirk it deals with answers one of the usual questions: Database Server disconnections due to the timeout. AXImageCanvas takes care of it when the connection is lost and if it is something not transient, then properly raises the exception so it can be cached by the application logic.

But one of the most important things is that everything can be configurable through the properties shown in the Inspector Panel of the Xojo IDE, for the maximum simplicity in the AXImageCanvas setup; and also via code to give the maximum flexibility at runtime when the application is in use, so it can react to things like changing the database engine, or simply disabling things like moving or resizing the control among others.

Pictures and Drawing Speed

What about redrawing concerns? This is something that AXImageCanvas also takes care of. It applies several image caching techniques while keeping the set Picture at its full resolution.

This allows, for example, abstracting you from what you can see displayed in the AXImageCanvas control at the desired size, from what you can do with the original Picture itself: from previewing it (something you can do simply pressing the space bar when the AXImageCanvas has the focus), getting more information about the Picture and (optionally) original FolderItem (press the ‘I’ key for that while the AXImageCanvas instance has the focus), or any other operation your app would want to do, like for example exporting the picture to other format.

In this sense, it also takes into consideration the operations done with the control itself during the redrawing or control size changes, minimizing the writing to the Database to the strictly necessary (always, of course, there is a database associated with the instance).

The Goals

To summarize, AXImageCanvas tries to be the simplest solution when dealing with Pictures and (optionally) its storage on databases. Just drop as many instances as you need in your layout, set the behaviour through the Inspector Panel Properties (even setting the initial picture to display) … and you’re done! The best part is that the behaviour will be the same for Windows, macOS and Linux deployed Desktop applications, both in 32 and 64 bits.

Of course, you can download the Xojo Project Example and try it yourself! This is a fully functional demo without restrictions. I’d be glad to hear from you about suggestions or features you would want to be included for better fit your needs!

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, GuancheID, AXImageCanvas, Markdown Parser for Xojo, HTMLColorizer for Xojo and the Snippery app, among others.

Last year at XDC 2018, Jérémie Leroy talked about making sure your screenshots mimicked the Apple method so that the date was always Jun 9th, the time was always 9:41 AM, the battery always shows as full and the WiFi strength always shows full. It got me thinking that it might be handy to be able to make the simulator always show those values when you do a debug run so that you don’t need to think about it when you are ready to start taking screenshots and movies of your app. One way to do that is to build & run project like SimulatorStatusMagic on the simulator before running your project, but it would be more useful if it was automatic.

Build the Framework

First of all, go to the SimulatorStatusMagic Github page and clone or download the project. Just like Xojo iOS development, you’ll need Xcode for this step. After you’ve downloaded the project, double-click on the SimulatorStatusMagic.xcodeproj file to open it in Xcode. When the project opens, change the target to SimulatorStatusMagiciOS and build it by either pressing CMD-B or pressing the Play button. Once the build is complete, go to the project navigator, scroll down to the bottom and open the Products group to reveal the built parts of this project. The only item we’re concerned with here is the file named SimulatorStatusMagiciOS.framework. Right-click on it and select Show in Finder.

Build the Project

Let’s start off by making sure the framework will be available to your project at runtime.

1. Create a folder on your drive named SimulatorStatusMagic and copy the framework file that you just built into it.
2. Launch Xojo and create a new iOS project. Save the project into that folder as well.
3. To make sure the framework will be available to your project when debugging, go to the iOS target in the Xojo navigator, right-click and select Build Step > Copy Files. Make sure the step is between the Build step and the Sign step.
4. Drag the SimulatorStatusMagiciOS.framework file from the Finder into the Copy Files Step.
5. In the Xojo inspector, set Applies To to “Debug” and Destination to “App Parent Folder”.

Now let’s make it so you can access the framework! We’re going to add this code in the App.Open event so that the status bar gets set up before you do anything else.

Getting the framework to load is fairly straightforward:

#If DebugBuild
  Declare Function dlopen Lib "/usr/lib/libSystem.dylib" (name As CString, flags As Int32) As Ptr
  Call dlopen("@executable_path/SimulatorStatusMagiciOS.framework/SimulatorStatusMagiciOS", 1 Or 8)
#EndIf

That magic string “@executable_path” gets translated into “wherever the current application currently is” at runtime. Now this just loads the framework. We still need to hook up the methods and properties. Note: If you’re working with a framework that “activates itself” like the one that comes with Reveal (an excellent tool for tracking down iOS layout issues), this is as far as you would need to go.

To figure out what we need to do next, we need to look at the documentation and header files that come with SimulatorStatusMagic. Go back to Xcode and look at the navigator. What we’re looking for is a header file (with a .h extension) which has the definitions of each of the methods and properties which are available in this framework. The only file that meets this criteria (and the one that all the others seem to point to) is named SDStatusBarManager.h. There’s a bit of functionality available here, but the framework is set up to use the Apple recommended settings by default, so all we’re going to do here is call the enableOverrides method to activate it.

Go back to Xojo and update App.Open event:

#If DebugBuild
  Declare Function dlopen Lib "/usr/lib/libSystem.dylib" (name As CString, flags As Int32) As Ptr
  Call dlopen("@executable_path/SimulatorStatusMagiciOS.framework/SimulatorStatusMagiciOS", 1 Or 8)

  // Start by creating a pointer to the SDStatusBarManager class itself
  Declare Function NSClassFromString Lib "Foundation" (clsName As CFStringRef) As Ptr
  Dim smclass As Ptr = NSClassFromString("SDStatusBarManager")

  // Next, we need a pointer to the shared instance of the SDStatusBarManager class
  Declare Function sharedInstance Lib "Foundation" Selector "sharedInstance" (clsref As Ptr) As Ptr
  Dim smclassShared as Ptr = sharedInstance(smclass)

  // Last, turn on the overrides
  // NOTE: We're specifically NOT using the actual lib name here. 
  // This is just to satisfy the Xojo linker. The correct framework will be used at runtime.
  Declare Sub enableOverrides Lib "Foundation" Selector "enableOverrides" (obj As Ptr)
  enableOverrides(smclassShared)
#EndIf

Now if you run the project, when it opens the status bar automatically changes to the recommended defaults!

Please Note: These changes persist until the simulator device that you are running on is completely erased. If you need to disable it, you can do that with the disableOverrides method.

After posting this article, it was brought to my attention that I’d forgotten to show you how to sign the frameworks so you can build for the app store. To do that, you’ll need to add a script build step to your project, just after the Copy Files step you added above. The step can probably be set to Applies To: Release. The code should look like this:

// Replace the text in the signingIdentity property with your own
Dim signingIdentity As String = "iPhone Distribution: Your Company (XXXXXXXXXX)"
Dim code As Integer
Dim cmd As String
Dim result As String
Dim builtApp As String

builtApp = CurrentBuildLocation + "/" + ReplaceAll(CurrentBuildAppName, " ", "\ ")

// Get a list of all frameworks, one per line
cmd = "ls -d1 " + builtApp + "/*.framework"
result = Trim(DoShellCommand(cmd, 30, code))

// If there was no error (like none being there), sign each one
If code = 0 Then
  Dim frameworks() As String = split(result, chr(13))
  For i As Integer = 0 To UBound(frameworks)
    frameworks(i) = ReplaceAll(frameworks(i), " ", "\ ")
    cmd = "/usr/bin/codesign -fs """ + signingIdentity + """ " + frameworks(i)

    Result = DoShellCommand(cmd, 30, code)

    // If the sign fails, print the error and stop the build
    If code <> 0 Then
      print Result
      cancelBuild
    End If
  Next i
End If