In programming, iterators are the mechanisms that run through all the items of a collection without needing to know in advance how many items compose that collection. To do this in Xojo, use the commands For Each… Next. What are the main differences when comparing For Each… Next with the conventional For… Next?

The first difference is that with For Each… Next we can’t assume that we are iterating the items in the collection in order, as is the case when using the variable of the conventional For… Next. The second difference is that the iterator will be invalid when the iterated elements are modified or when we modify the number of elements in the collection during the iteration process.

By default in Xojo, there are a couple of collections that are iterable: Arrays, Dictionaries and FolderItem.Children. Wouldn’t it be great to extend this behaviour to other classes, making them more flexible? The key to doing just that is in two of Xojo’s Class Interfaces: Iterator and Iterable.

Download the example project used in this tutorial.

Using Iterator

In order to implement this behaviour in our classes so they can use the For Each… Next schema, the real work is in the Iterator Class Interface. Under this interface, we can find the definition of the methods that are needed to implement the class and that are responsible for advancing every item of the collection, and for returning the current value of the collection:

• MoveNext. Moves to the next element of the Collection, returning True if it has not reached the end of the collection, Falsewhen reached past the last element in the Collection.
• Value This is the Class Interface method that returns the current element of the collection as an Variant data type.

From this, it is easy to conclude that our iterable classes need to implement a counter (as a Property) that updates its value for every MoveNext invocation. We will also use this property to check if it has reached the maximum number of elements. Also, be aware that the property has to be initialized using the value -1 (that is, as an invalid value), as it is stated in the documentation that we have to invoke MoveNext before we can get the first iterable element from the collection.

On the other hand, we will handle all the error cases during the iteration process raising IteratorException.

In order to see all this in action, let’s run through an example using the Personclass in charge to store in their instances all the possible postal addresses associated with a person.

Let’s start defining ourPersonclass as a simple set of Properties:

• firstName As String
• middleName As String
• secondName As String

Also, add the Property in charge of referencing all the postal addresses assigned to the Person, using an Array:

• postalAddresses() As PostalAdress

With that, we have finished our Person class definition. It’s very simple but works for the purpose of this example.

We will also create a simple (and incomplete) definition for the PostalAddress class using a set of public properties so they serve the purpose of the main topic.

• street As Text
• streetNumber As Integer
• streetFlat As Integer

Creating an Iterator

Once we have the two classes needed for our example (Person and PostalAddress), we can define the Class responsible for acting as the iterator; that is, returning every element from the collection for the associated class. In this example we will return every object of the PostalAddress that is associated with an instance of the Person class. In fact, the Iterator is responsible of doing all the hard work, moving forward the counter to the next item, and returning the object or value when requested.

Let’s create a new Class with the namePersonIterator. In this case, use the associated Inspector to select theChoosebutton next to theInterfaceslabel. This will display a window containing all the available Class Interfaces. Select the checkbox forIteratorand confirm the selection.

The IDE will now add the following defined methods for the selected class interface:

• MoveNext. The documentation states that this is the method invoked before calling the Value method in order to get a new value. In fact, in the method implementation we have to write the code that increases the counter value, and also checks if the counter value is over the available quantity of items. Meaning, we have to add acounterProperty to our class, and initialize it with the value -1.
• Value. This is the method that will be called every time we need to get a new value. In our example, this will return a new PostalAddress object from the available items.

Thus, the implementation for theMoveNextmethod could be the following:

counter = counter + 1

But the method signature and the class interface documentation states that the method has to return a boolean value ofTrueif there are remaining available items to iterate andFalseif the quantity of iterable items has been surpassed. In the case we should raise an exception in order to point this out.

For example, our class could check if the counter doesn’t exceed the quantity of items stored by the PostalAddresses Array, returning the corresponding boolean value.

But let’s fill in some holes before writing the final implementation for theMoveNextmethod. First, let’s add some more needed properties:

• maxPostalAddresses As Integer. This will be responsible for storing the number of elements available under the PostalAddress Array.
• source As Person. This will be in charge of saving the reference to the Person object it has to iterate.
• The Calculated Property valid as Boolean. We will use theGetmethod from this calculated property to know if the PostalAddress Array has been modified during the iteration of the object, returningFalse when this is the case. In fact, this is the code for theGetmethod:

Return if(source.postalAddresses.LastIndex = maxPostalAddresses, True, false)

Next, we will add theConstructormethod to the class using this signature:

Constructor( value As Person )

and the following code for the method:

source = value
maxPostalAddresses = value.postalAddresses.LastIndex

This initialized the previously declared property’s values with the reference to the Person object that we will use to iterate over, and the number of elements included in the Array when we initialize the class. Thus, the number of original items that we will use to check if it has been modified during the iteration process.

Now we can move back to theMoveNextmethod to write the final implementation:

If valid Then
  counter = counter + 1
  Return If(counter <= source.postalAddresses.Ubound, True, False)
Else
  Var e As New IteratorException
  e.Reason = "Invalid Data"
  Raise e
End If

Inside the method implementation we will also check if the object has been modified during the iteration, returning the corresponding value:

If valid Then
  Return source.postalAddresses(counter)
Else
  Var e As New IteratorException
  e.Reason = "Invalid Data"
  Raise e
End If

As you can see, the Value method will return the PostalAddress item from the Person array, using the value of the Counter property as Index.

Creating the Iterable Class

Now we have to create the iterable class itself. Add a new class to the project with the name IterablePerson and make it a subclass from the Person class. Write this data type in theSuperfield of the Inspector Panel. In addition, this class will be the one that implements the class interface Iterable, so you have to push on theChoosebutton associated with theInterfaceslabel in order to select and confirm the addition of the corresponding methods. In fact, is just one method:

Iterator() As Iterator

And this is the code for that method:

Var it As New iterablePerson(Self)
Return it

Now we have all the definitions we need for the subclass: we get a new IterablePersoninstance passing as a parameter the iterable object (a Person subclass). Finally, we return the iterator we got and that will be used inside theFor Each… Nextloop.

Putting It All Together

Armed with all the needed classes for our example, we can finally put it all into practice. For this, add a ListBox in the main project Window (Window1). This is the control where we will add as many rows as there are postal addresses associated with an instance of the Person class used for the example. For this, add a button to the window with the Action event and write the following code in the resulting Code Editor:

Var p As New IterablePerson
p.firstName = "Juan"
p.middleName = "Sin Miedo"
p.secondName = "De Nada"
Var d As New PostalAddress
d.street = "Juan de Urbieta"
d.streetNumber = 6
d.streetFlat = 1
p.postalAddresses.Add(d)
d = New PostalAddress
d.street = "Mi calle bonita"
d.streetNumber = 8
d.streetFlat = 3
p.postalAddresses.Add(d)
d = New PostalAddress
d.street = "Princesa"
d.streetNumber = 5
d.streetFlat = 5
p.postalAddresses.Add(d)
For Each s As PostalAddress In p
  Listbox1.AddRow(s.street + ", " + s.streetNumber.ToString + " Piso: " + s.streetFlat.ToString)
Next

Run the project, push the button and you will see how theFor Each… Nextloop iterates every postal address associated with the Person object. This is a more concise, stylish and OOP way of doing things when compared with the classicFor… Nextloop, which requires getting the upper value (or limit) and use a variable as index to get every collection object we are interested in.

*This blog post was originally written by Javier Menendez in 2017 and has been updated for Xojo API 2.0 by Wayne Golding.

Wayne Golding has been a Xojo developer since 2005 and is a Xojo MVP. He operates the IT Company Axis Direct Ltd which primarily develops applications using Xojo that integrate with Xero www.xero.com. Wayne’s hobby is robotics where he uses Xojo to build applications for his Raspberry Pi, often implementing IoT for remote control.

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.

The main advantage of a class hierarchy is that all the derived classes share the same set of methods, properties and events declared in their upper classes (those not set with a Private scope) and, thus, we can make our code more flexible, easier to maintain and get more dynamism from our apps at run time thanks to the Casting of types.

Download the Demo Project

What is this all about? Very simple. For the subject at hand, every graphic control or User Interface (UI) control included in the Desktop Xojo Framework share the common base class RectControl (this one based, at the same time, on the base class Control); and among the methods available in that class we can find DrawInto.

This means that every UI control has the ability to draw itself in any given Graphic context. However, when drawn in the target graphic context they will lose their usual response to any user interaction. That is, they would be a mere graphic representation of themselves; something that is really useful in many cases. For example, this is the technique used for drawing all the contents of a given page or range of pages in AXControlGrid.

As you can see in the Xojo documentation, the DrawInto signature is as follows:

RectControl.DrawInto(g as Graphics,x as Integer, y as Integer)

• The first thing you can see is that the method is called on the instance (UI control) we want to draw into a given graphic context.
• Second, the first argument we provide in the DrawInto method is the graphic context we want to use to draw the control. As you probably know, we can get such graphic context from several kind of classes, for example Picture. In addition, the target graphic context can be of any size we need it to be!
• Third, the x and y arguments are the top-left coordinates used to draw the control in the target graphic context and, of course, these coordinates should be in the range of the width and height of the target graphic context passed as the first argument.

For most of the cases, you don’t need to do anything special to use this method in your own classes. That means that the object calling the DrawInto method will draw itself using the same code you put in its Paint event. The unique difference in this case is that the Paint event will use the external graphic context and receive x and y coordinates that may be (or may not be) outside its own width and height range.

But there might be other times you don’t want to draw the control using the same code as the one written in the Paint event. Maybe because you need a more refined representation of the control or you simply want to leave out some details that are useful when the control is drawn as part of the UI but not when it is printed or used in a PDF document. In addition, it can be the case that inside the Paint event you may need to do some calculations on the x and y coordinates that would not make sense (or would be out of range) when done on an external graphic context.

After all, the key about using DrawInto is this:

• When a instance calls this method, what really happens is the code in the Paint event will be executed on the new graphic context received as argument. Of course, if you have not implemented the Paint event yourself, then Xojo will execute the default implementation.

Customizing the DrawInto Behavior

In other cases, especially on Windows, it is possible that we won’t get the right drawing when using the default implementation of the DrawInto method. If you find yourself in this situation, you can fix it by overwriting the DrawInto method for your own UI classes.

When you do that, evey time you call this method it will execute the code you included in it, and that means that you will be in control of the received graphic context as parameter, its size and origin coordinates, and especially the drawing operations available through the methods from the Graphics class.

The way to implement (overwrite) the DrawInto method in your own UI controls (derived from the RectControl class) is as simple as for any other overwritten method or Event in your own subclasses.

With your class selected in the Xojo IDE Navigator, access the contextual menu to select the Add to "instanceName" > Method option, choosing the DrawInto(graphics as Graphics, Left as Integer, Top as Integer) item in the Name field popup from the Inspector Panel.

Once selected, you will see that the associated Code Editor will contain by default a call to the same method signature on the Super class. This gives the class the control is based on the oportunity to drawn itself.

From a practical point of view, you will probably want to delete that call when you don’t want to use the same kind of representation for the control on the external graphic context when that is drawn in the UI. In addition you will save some drawing time thus improving the overall speed.

Now you only need to include in the DrawInto method the code you want to use in order to paint your control on the received context and you’ll be set! From that point on, every time you call:

aRectControlInstance.DrawInto( tContext, 100, 100 )

Xojo will execute the code put in your own implementation of the DrawInto method, and that means more flexibility and control about what is drawn and how it is drawn; especially if your UI control is going to be used both in macOS and Windows.

DrawInto in Practice

In order to see how everything works, let’s create a simple Xojo Desktop project where we will make use of our own DrawInto implementation on one Canvas based class.

Create a new Xojo Desktop project, drag the Canvas control from the Library panel into the Navigator.

Next, and with the new Canvas class selected, access the Inspector Panel to set the following values:

• Name: MyOwnControl
• Super: Canvas

With our new class still selected in the Navigator, add the Paint Event. For that, you may access the contextual menu and choose the Add to "MyOwnControl" > Event Handler…" option, selecting the Paint entry afterwards in the resulting window.

Then, write the following code in the Code Editor associated with the Paint Event:

g.DrawingColor = &cff0000
g.FillRectangle(0,0,g.Width, g.Height)

Nothing especially significant here. As you can see, it sets the foreground color to Red and then fills all the control area using the FillRect method on the control graphic context.

Now it is time to overwrite the DrawInto method. With our class still selected in the Navigator, add the DrawInto method and write the following code in the associated Code Editor:

// Uncomment the following line of code to see what happens!
// In that Case, the control first executes the code from the Paint Event,
// executing the drawing code from the overriden DrawInto method afterwards.

//super.DrawInto(graphics, left, top)

Var s As String = "From DrawInto"

Var sLen As Double = graphics.TextWidth( s ) / 2

graphics.DrawingColor = &c00FF00

// No matter what the "Left" and "Top" values are, we don't use them
// for our custom drawing.

graphics.DrawRectangle(0,0, graphics.Width, graphics.Height)

graphics.DrawingColor = &c000000
graphics.PenSize = 1
graphics.AntiAlias = True

graphics.DrawText("From DrawInto", (graphics.Width/2) - sLen, (graphics.Height / 2) )

Basically, what we are doing here is substantially changing the graphical representation of the control between what is seen when it is drawn in the user interface through the Paint Event and what we will get when calling the DrawInto method on the Control instance.

In the second case, it will draw a non-filled green rectangle using the same width and height that the control itself, writting the string “From DrawInto” centered in the control area.

You can see that the Super.DrawInto(graphics, Left, Top) code line is commented. After the initial running of the demo app, you can uncoment that line if you want in order to see how it changes the drawing when the Super class is called (remember, that means executing the code on the Paint event for the Class).

Putting it all Together

With our class already finished, it is time to start the layout of our minimal user interface. Something really simple. Choose the Window1 window in order to access the Layout Editor. Then drag the MyOwnControl item from the Project Broswer into the the Window1 area in the Layout Editor. With that action we will have added a new instance from our class. The resulting name for the instance will be MyOwnControl1.

Then, drag a standard Canvas control from the Library panel into the Window1 area in the Layout Editor. This action will result in the creation of a new Canvas instance with the by-default name Canvas1.

Lastly, add a new button from the Library into the Window1 area in the Layout Editor and use the Inspector Panel to set its name to pbDrawInto and its caption to “DrawInto”. This will be the button in charge to order our MyOwnControl1 instance to draw itself in the graphic context provided by Canvas1.

For that, and with the pbDrawInto selected, add an Action Event Handler and write the following code in the associated Code Editor:

// We create a Picture we can use to give a Graphics context to the
// Canvas1 backdrop (it would be "Nil" by default)

Var p As New Picture( canvas1.Width, Canvas1.Height, 32 )

canvas1.Backdrop = p

// And we instruct our "MyOwnControl" instance to draw itself on the
// "Canvas1" graphics context.

MyOwnControl1.DrawInto(Canvas1.Backdrop.Graphics,0,0)

If you want, you can layout your user interface like the one displayed in the following screenshot:

Now we have our app ready to test. Press the Run button in the IDE and verify the results you get between what is drawn by the Paint Event and what you get when you click on the button labeled “DrawInto”.

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, AXControlGrid, AXImageCanvas, Markdown Parser for Xojo, and HTMLColorizer for Xojo among others.

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.

Sometimes, subclassing the available controls is the answer to add specific behaviors you need. But what happen when none of the controls offer what you need, whether visually or functionally? The answer is the Canvas class (for Desktop projects), WebCanvas class (for Web projects) and iOSCanvas class for iPhone and iPad devices. But how do you create your own UI controls from scratch? Read on to learn…

Before starting with this basic tutorial about customized UI controls, there is much more to take into consideration about providing the same behavior on your designed controls for multiplatform deployments. For example, in the case of desktop projects, we should add to the mix some things like HiDPI / Retina detection and adaptation on the fly (specially in the case of Windows deployment, with multiple dpi / Windows OS version combinations), and Dark Mode support for macOS. A well as other performance hints and differences when it’s about doing desktop multiplatform layouts; for example, when to set the Transparent or DoubleBuffer properties to True or not.

As the name implies, the Canvas control acts like a painting canvas and you can set its look for all the supported states based on the available events. This is done through the Paint Event and all the Graphic classes availables in the Framework. In fact, the Paint event provides as a parameter the graphical context (canvas height and width) you can paint on. In addition, you can combine these graphic classes (or completely substitute them) with any prepared Picture of your choice as the customize control background (ImageSet recommended, so it supports all the needed resolutions based on display dpi). In addition, and as you can do with the drawing via the Graphic class and functions, you can choose to use a different Picture as the control background based on several events, for example, when the mouse pointer is entering or exiting the control limits in a Desktop or Web app, or as response to the user clicking on it.

Canvas: A matter of Events

The Canvas class provides all the needed Events you probably would want to implement in order to react to the user interaction. These are listed and described in the available documentation online and as part of the Xojo IDE interactive Help.

While you can drag and drop a Canvas instance directly to your project layout window or view, implementing and writing the code associated with  any of the available Events, the recommended way to go is to create your own subclass taking as its parent the Canvas class. This way, you can implement and fine-tune every aspect that makes you control unique and, most importantly, re-use your customized UI controls as many times you want both in current and future projects (or even offer them to the Xojo community or sell them to other developers!).

As you probably already know, in an OOP programming language, subclassing is the method to get a specialized behavior from an existing Class: We get for free all the available properties, methods and events from the parent (and all its parent hierarchy), including also the code executed in the Paint event to truly paint or provide its look on screen; so we just need to implement the specific behavior and/or control drawing/painting we need over these.

This is also the way to go when you are in the inital stages of designing your own customized UI control: will you need to create even more specialized behaviors based on a “parent” or base customized control? Maybe variations on the behavior? In cases like these, you should define your UI control base class at the bare-minimum set of painting, behavior (events and methods) and properties that will be shared from all the future UI Controls inherited from your base/parent UI Control class. (i.e: more specialized or with behavior variations).

Creating a subclass in Xojo is truly simple: just drag and drop the Canvas icon from the Library to the Navigator (the leftmost column in the Xojo IDE), or choose Insert > Class from the Insert menu.

Points vs Pixels: HiDPI and Retina

Once you have added the new Class to your project, select it, go to the Inspector and set the name you want to use for your new Class (using a “company” or personal prefix it’s always a good idea to avoid collision with other existing or future classes in the Xojo Framework, or when using third party classes). Then, in the Super field of the Inspector Panel, type Canvas and confirm the entry. You’ll see how your class icon changes to the one that uniquely identifies Canvas based classes and instances. The most important thing: your new subclass will have all the properties, events and methods you may expect from a Canvas.

This will be the base class in our short tutorial for creating a customized button that will change its associated image (picture) when the mouse pointer is inside the button area, outside the button bounds or when the user click on the control. In the last case, the button will change both the image and its internal state represented by a property as a Boolean value (named Status).

As our customized UI control will not draw itself via the Paint event, we will need to design the images so these precisely fit in the size we want to use for our button. In this example a size of 32 x 32 points.

In general, when designing images to use in our Xojo projects we need to change our mindset from thinking in pixels to points. That’s because Xojo apps do support HiDPI on Windows/Linux and Retina on macOS; that is: hi-def graphics. Thus, it’s important to use a design tool that simplifies the process. Personally, I use the vectorial app Sktech on macOS because it automates the 2x creation of the final images. (Remember that HiDPI/Retina is enabled by default in the Building Settings on every new Desktop project.)

How do you support HiDPI/Retina if you want to draw the control look on the fly? Avoid the use of pixels in your calculations or when setting the values of the existing Graphic class properties, and use Points instead. If you really need to access the Pixels values underneath, then you can resort to the RGBSurface class (if available) and make use of the ScaleFactorChanged event available on the Canvas class. This way, your class will be notified on every change between displays with or withour Retina/HiDPI support.

Good rule of thumb: do all your control drawing inside the Paint event! And, when you need to update or redraw it (maybe as consequence of some change in the app behavior, or from the change made in other UI control), invoke the method Invalidate instead of Refresh. In general, this will speed up the drawing and, thus, the main app performance.

If you use an existing Event… Define the Event again

As our customized class makes use of the Open, MouseEnter, MouseExit and MouseDown Events, we need to make sure we define these events again to the class, so they are also available for the developer using our canvas-based UI subclass. After all, it’s very probable he needs or wants to add extra code on top of ours! This is something we can do choosing Add to "class_name" > Event definition when our subclass icon is selected in the Navigation Browser.

Thus, once we have created the same events (using the same parameters and returning the same kind of Type values as the original ones), we need to make sure we call them; usually as the last line of code for the already used Event. For example, this is the code for our implementation of the MouseDown event in our Canvas subclass:

me.Backdrop = if(me.Status = false, ShellRunSelected, ShellRun)
me.Status = not me.Status
return RaiseEvent MouseDown(X, Y)

Note how, in this case, our implementation of the MouseDown event returns the value returned by the consumer of our subclass instances, called with the RaiseEvent statement. Just remember that returning the True value from this event means that such events will not be propagated further along the Events Chain.

Putting it all Together

With this information at hand, and the basic concepts explained, this video (in Spanish) shows how you can join all the needed pieces: pictures, events, definition of already consumed events by the subclass; creating a new very basic control from scratch. Obviously, from this point on, you can find in the available documentation all the information needed to create more complex UI controls based on the Canvas class (WebCanvas or iOSCanvas). The possibilities are limitless!

Other useful topics:

• User Guide: Desktop Canvas
• Canvas, Graphics classes
• User Guide: iOS Canvas
• User Guide: Web Canvas

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

*Read this post in Spanish

But, beware! The following implementation will delete all the files and original containing folder every time it finds an alias… not just the alias. Anyway, it is easy to change this behavior in case you just want to delete the alias and not the original it points to.

As you probably already know, when we work with files or folders in Xojo we are actually using the FolderItem class, so we are able to access to all its properties and the methods acting on every instance: changing the file/folder/directory name, getting the creation date, create a copy, to move the file and/or folder to a new destination … and also for deleting the file or folder.

In addition, recursion is a technique that is not always appropriate because the function adds a new frame of data to the execution stack every time it calls itself, something that can cause a stack overflow error if it calls itself a large amount amount of times. This may occur, for example, if a folder or directory has many nested folders. To alleviate this, we can resort to the mechanism provided by the Xojo language itself and gracefully catch this situation on runtime.

Having said this, what is the best way to implement our recursive function so it is available to all the FolderItem instances? You may create a new FolderItem subclass, but that would mean that the method would only be available from the instances created from the subclass, and not for those created from the parent FolderItem class. The answer in this case is to apply it as a Class Extension technique. This technique allows us to add additional functionality to a existing class without needing to subclass it previously.

The way to add a Class Extension in Xojo is through a Module, so it gives us the option to set the method as globally available from all the app code. This way, the Xojo compiler will know that we want to extend a particular class because we use the Extends keyword in the method definition, followed by the variable whose data type designates the class we want to extend.

So, our method (or function) signature will be:

DeleteAllFilesInside(extends f as FolderItem)

Once we’ve added that method to a Module it’s important to set the Scope to the value Global in the Inspector. Now we can put the following code inside the associated Code Editor for the method, so this is the responsible of deleting the files and call itself every time it detects a new folder/directory:

  // We keep the initial (designated) FolderItem
  // So it doesn't get deleted.

  Static originFolder As String = f.NativePath

  // Is the pointed FolderItem a Directory?
  // then proceed to iterate the containing
  // files and (probably) folders.

  If f.Directory Then

    For n As Integer = f.Count DownTo 1

      If f.Item(n) <> Nil Then

        // Are we detecting a new folder
        // while iterating the current one?
        // then we call the function again!

        If f.item(n).Directory And f.Count <> 0 Then

          Dim f1 As FolderItem = f.item(n)

          f1.deleteAllFilesInside

        End If

        // Otherwhise, we proceed to delete the file/folder
        // always it is not the initial FolderItem
        // that is, the initial folder/directory

        If f.item(n) <> Nil And f.item(n).NativePath <> originfolder Then f.item(n).Delete

      End If
      
    Next
  End
  
  // we are outside a folder, so let's check
  // that the pointing FolderItem is not the initial one
  // if it doens't, then we can delete the file/folder

  If f <> Nil And f.NativePath <> originFolder Then f.Delete

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

*Watch a video of this Tutorial in Spanish

*Read this post in Spanish

However, by using a little JavaScript you can easily add this capability to Xojo.

In order to follow this tutorial, create a new Web project and add a new WebCanvas control from the Library to the default Web Page added to the project: WebPage1. With the WebCanvas selected in the Navigator, change its name to cCanvas using the Inspector and add the Paint Event Handler to it using the Insert > Event Handler option from the menu. Use the following code to draw a black colored rectangle:

g.FillRect 0, 0, g.Width, g.Height

Obviously, you can draw anything you want in the WebCanvas or even paint a picture on it. The achieved result will be the same. For example, we can draw a picture added to our project (with the filename “landscape”), using this line of code in the Paint event of our cCanvas instance:

g.DrawPicture landscape, 0, 0, g.Width, g.Height

Retrieving the WebCanvas image data

The first interesting step is retrieving the underlying image represented by the WebCanvas and that is something we can get using a fragment of JavaScript code executed from the Xojo side. This is the process we will execute from the Action Event Handler of a WebButton added to the WebPage1 from the Library. In fact, this will be the button in charge of calling the process to save the image as a picture file on the user disk.

Once the WebButton has been added to the WebPage from the Library, put the following code in its Action Event Handler:

Dim js() As String
js.Append "var canvas = document.getElementById('" + cCanvas.ControlID + "_canvas');" // We get the item reference based on its ID
js.Append "var img = canvas.toDataURL(""image/png;base64;"");" // We access to the image data, encoded as a base64 string
js.Append "document.location.hash=img" // We assign that data to the document Hash property, so we can retrieve it from the Xojo side

Dim execute As String = Join(js,"")

ExecuteJavaScript execute // Finally, we execute the JavaScript code

As you can see, the first line of the JavaScript code is in charge of retrieving the cCanvas reference from the DOM (document object model) of the Web Page. For that, we use the ControlID property on our WebCanvas instance, adding the “canvas” appended by Xojo to all these kind of objects when generating the source code for the page.

Once we get the reference to our Canvas instance, the following line of code retrieves the picture content itself and assigns it to the img variable. The trick here is that we retrieve that information in its URL format and, thus, encoded as Base64 data that we can assign to other document properties without losing its original meaning.

Then, we assign the data to the document Hash property. This is the property that allows us to jump to other page sections previously tagged. However, we will use this property as a temporary storage container for passing the data between the HTML/JavaScript side of the web page and the Xojo side of our code. Why we do this? Well, because we can add the HashTagChanged Event Handler to the Session object so it will fire every time we change the value of the Hash property and we will be able to retrieve the data from that property.

Retrieving the image, from the Xojo side

So, the next step is adding the HashTagChanged event to the Session object of our example project, writing the following snippet of code in the associated Code Editor:

Dim data As String = DecodeBase64(Hashtag.NthField(",",2) ) // We retrieve the information saved in the Hash, but just the relevant data for the image and not the URL part.
wp = New WebPicture(data,"My_Picture.png") // We create a new WebPicture instance using the previously retrieved image data in the constructor, and giving a default file name for the image
wp.ForceDownload = True // We want to force the file download instead of showing it
ShowURL wp.URL // and finally we start the file download process.

Hashtag = "" // Let's empty the hash property, just to make sure that the event will fire even if the WebCanvas doesn't change its contents

As you can see, in the first line of code we retrieve the image data. We do that using the NthField command because we are only interested in the image data and not in the URL information that precedes it. In addition, we decode the previously encoded data as Base64, so we really get the bytes of the image in PNG format.

Once we get the picture data, we can use any of the available constructors for the WebPicture class; in this case the one that lets us create a new image from the passed data. In addition, we use this class because it is a subclass of WebFile, and that means that it is simpler to force the download as an image file instead of showing its contents in a new web page.

In fact, this is what we achieve setting the ForceDownload property to True, so when in the following line we use ShowURL we will be forcing the download of the file instead of displaying the image as a new page in the browser. Goal achieved!

Download persistence

You probably noted that the wp variable is not declared in the previous fragment of code. This is because we need to make sure that the object it points to is in scope during the file downloading process and won’t get destroyed once we exit the Event Handler (we would want a message error from the web browser in that case). The solution is pretty easy – we only need to add a new property to our Session object, using the following values:

• Name: wp
• Type: WebPicture
• Scope: Private

Now, every time you run the app web and click the button, you’ll see how the web browser downloads the WebCanvas image as a PNG file to disk.

To summarize, in this tutorial we have seen a way to “communicate” between the data generated executing JavaScript code in our web app so we can retrieve and use it from the Xojo side of our Web App; in this case applied to the retrieval and saving of the underlying picture represented by a WebCanvas object.

*Watch a video of this Tutorial in Spanish

*Read this Tutorial in Spanish

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, HTMLColorizer for Xojo and the Snippery app, among others

For software, distribution usually means generating and validating unique serial numbers for each of your products and users. Serial numbers (or license keys) help you manage your users, unlock a free trial or demo version for full use and, of course, minimize illegal use of your apps.

Let’s admit it, there is no silver bullet. Even the greatest companies (you know who you are) throw lots of money at implementing and improving serious protection schemes that are often quickly bypassed.  It comes down to: How much time, money and resources are you willing to spend implementing a protection or licensing scheme?

The bad guys will always find a way to break your software protection if they are interested in doing that. Does that mean giving up on protecting your software? Not at all! When I was faced with the problem myself, in order to protect my own products, I went to the drawing board to build a way to generate unique serial numbers —or licensing information— for all the Xojo supported platforms.

The result of this process was the GuancheMOS plug-in. GuancheMOS is a fully multiplatform plug-in for desktop, web and console apps (not for iOS due to the fact that iOS only can link against static libraries), on 32-bit and 64-bit architectures.

The simplicity of GuancheMOS means that you can use it as is, or as the starting point to build your own private and unique serial number automations. Integrate it as part of the purchase process in your website, wrap it as the core piece of other unique information collection. It’s already used by dozens of developers around the world in ways I hadn’t ever thought of while designing it! The best part, is that implementing GuancheMOS in your product takes about 5 minutes.

You can download and try GuancheMOS for free today.

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, HTMLColorizer for Xojo and the Snippery app, among others

For example, it would not be desirable to send hundreds of emails to all the entries in a database simply to test one of the workflow steps or to verify that emails are being delivered as expected. It would be a lot simpler, and less disruptive to those using your app, to test using a few email addresses that are under your control.

So let’s establish a mechanism that allows us tell our apps when to run in a “simulated” mode vs. a “real” mode for all or some of the components that we need to test along the development cycle.

In fact, the way we can implement this is very simple and is based in the definition of a Boolean property in every class (let’s call it Simulation) that we can make visible under the Inspector Panel using the Inspector Behavior feature. Doing this, we can also change it when we drag and drop the class on the Window Layout tray in order to create an implicit instance.

In association with the property itself, we will implement every public method that will be called from the consumer (other component or code of the app) as usual, with the only difference that we will add two additional private methods for every public method we want to run in both modes: simulated and real. For example, let’s say we have a class that returns a Dictionary array with data from a database. We create a public method for the class, called GetData, but when we just need to test other components it provides some fake data instead of connecting and retrieving a bunch of real data from the remote database. In this case we could define the following methods for the class:

• GetData() As Dictionary(). Public Method, part of the visible interface for the rest of the app.
• GetRealData As Dictionary(). Private Method, called if the Simulation property is set to False.
• GetSimulationData As Dictionary(). Private Method, called when the Simulation property is set to True.

Then, the real code for our public method will be simply this:

Return if(Simulation = True and DebugBuild = True, GetSimulationData, GetRealData)

Simple, isn’t it? With this you will have the maximum flexibility to choose the functionality you want to test using real or simulated data: all, none, part of them … even when you deploy the compiled project it will work always with real data.

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, HTMLColorizer for Xojo and the Snippery app, among others

*Read this post in Spanish

Before we put our hands on it, let’s make some things clear about the Control Set:

• You can use this feature to dynamically create any kind of control based on the RectControl class.
• You can use Control Sets on Desktop and Web projects (although web projects cannot use Control Sets to dynamically create controls at runtime).
• You cannot create Control Sets for Container Controls.
• The Control Sets may seem like Arrays, because you will use an index to refer every instance from the same Control Set, but they are not. So, don’t think about them in that way.
• All of the instances of the Control Set will share the same Event Handlers, so you will have to use the additional index argument, passed to the Event Handler, in order to identify over which instance are you handling.

But, how can we create one of these Control Set after all? Well, we just need to put any control we want to use as a clonation template on the Window, even if it is placed outside the visible limits of the Window itself. Then, and with the control still selected, you just have to push on the attributes button (the one with the image of a gearwheel) on the Inspector, selecting the New Control Set option from the Member Of entry under the Control Set Section.

Tip: If you change the name of the Control used to create a Control Set, then you will have to recreate the Control Set, so rename the template Control in the first place!

Once you have created the new Control Set, you will see that the first instance of the Control Set is assigned the index number 0; succesive instances will have their index increassed by one, both the ones you may add to the Window (not what we want to do in this case), and those created at runtime (what we want to do).

Now, probably you will want to change the Visibility Property to False on this first cloning template control, so it will not be visible to the users of the app no matter the resizing of the containing Window.

Once our cloning control is all set, it’s time to reveal all the code we will need in order to create new instances of the control at run time. Let’s indicate that we have used as cloning template Control a PushButton and that we have named it btClon. Then, we just need this to create a new instance, making it visible on the Window:

Dim newInstance as PushButton = new btClon
newInstance.visible = true

Remember that every UI component is based on (inherits from) the RectControl class, so you also can do this:

Dim newInstance as RectControl = new btClon
PushButton(newinstance).visible = true

As you can see, the difference is that in this case you have to Cast the generic RectControl instance to the PushButton class in order for you to use and access all the PushButton methods and properties from code.

Why should you use this formula, then? Well, if you are thinking about creating several Types of UI components at runtime, then you will probably prefer to create them using a more generic RectControl variable or reference (maybe a RectControl Array containing all of your dinamically created controls).

As you may expect, the new instances created from a template will have the same properties, events and methods the template control has, with the difference that it will also inherit the clone properties values. This is why once a new instance is created we need to make it visible again and you will want to change other properties too, for example the Caption and the Left and Top properties among others.

Modifying the Z axis order of the Control

We already know that every new created instance of the Control Set gets its index increased by one. What you have to know is that every new instance is above the previous one on the Z axis of the Window. I mean, if the control with the Index set to 2 partially overlays the position of the control with the Index 1, then the first one will overlay the second. What if you decide to have a control with a low index value above the others?

Currently there is no easy way we can dynamically change the Z order of a control to any desired value, but there is an easy way we can move any control to the foreground, so it can stay in front of all of them!

Let’s say that we have our cloned control with the Index 1 and want to show it in the foreground, with the highest possible value in the Z axis. All we have to do is assign it to another RectControl as its parent property value, for example the control we are using as cloning template. Once done, we will assign the Window again as the parent property value of the control. The code could be something similar to this:

btClon(2).parent = btClon(0)
btClon(2).parent = Window1 //Or Self or Me, depending where you place the code

In conclusion, as you can see, the creation of UI controls at runtime is something really easy to do in Xojo! But what if you need to dynamically add a group or layout of control at runtime? Well, in that case don’t forget about the ContainerControls!

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 and the Snippery app, among others.

*Read this post in Spanish

*Watch the video in Spanish

The first difference is that with For Each… Next we can’t assume that we are iterating the members of the collection in order, as it is the case when using the variable of the conventional For… Next as the Index in order to access a known member of the collection. The second difference is that the iterator will be invalid when the iterated elements are modified, or when we modify the amount of elements in the collection during the iteration process.

By default in Xojo, there are a couple of collections that are iterable: the already mentioned Arrays and also Dictionaries and FolderItem.Children. Wouldn’t it be great to extend this feature so we can add this behaviour to our own classes making them more flexible? The key to making this happen is using the two Class Interfaces already included in Xojo: Iterator and Iterable.

You can download the example project used by this tutorial from this link.

Using Iterator

In order to implement this behaviour in our classes so they can use the For Each… Next schema, the real work is under the Xojo.Core.Iterator Class Interface. Under this interface we can find the definition of the methods that need to implement the class and that are responsible for advancing for every item of the collection, and for returning the current value of the collection:

• MoveNext. Moves to the next element of the Collection, returning
  True if it has not reached the end of the collection, or False when reached past the last element in the Collection.
• Value This is the Class Interface method that returns the current element of the collection as an Auto data type.

From this, it is easy to conclude that our iterable classes need to implement a counter (Property) that updates its value for every MoveNext invocation. We will also use this property to check if it has reached the maximum quantity of elements. The only thing we need to be aware of is that the property has to be initialized using the value -1 (that is, as an invalid value), as it is stated in the documentation that we have to invoke MoveNext before we can get the first iterable element from the collection.

On the other hand, we will handle all the error cases during the iteration process raising an IteratorException.

In order to see all this in action, let’s run through an example using the Person class in charge to store in their instances all the possible postal addresses associated with a person.

Let’s start defining our Person class as a simple set of Properties:

• firstName As String
• middleName As String
• secondName As String

We will add also the Property in charge of referencing all the postal addresses assigned to the Person, using an Array:

• postalAddresses() as PostalAdress

With that, we will have finished our Person class definition. It’s very simple but will work for the purpose of the example.

We will also create a simple (and incomplete) definition for the PostalAddress class using a set of public properties so they serve the purpose of the main topic.

• street As Text
• streetNumber As Integer
• streetFlat As Integer

Creating an Iterator

Once we have the two classes needed for our example (Person and PostalAddress), we can define the Class responsible for acting as the iterator; that is, returning every element from the collection for the associated class. In this example we will return every object of the PostalAddress that is associated with an instance of the Person class. In fact, the Iterator is responsible of doing all the hard work, moving forward the counter to the next item, and returning the object or value when requested.

Let’s create a new Class with the name PersonIterator. In this case, use the associated Inspector to push on the Choose button related with the Interfaces label. As the result of the previous action, the Xojo IDE will display a window containing all the available Class Interfaces. Select the checkbox for Xojo.Core.Iterator and confirm the selection.

As result of the previous action, the IDE will add the following defined methods for the selected class interface:

• MoveNext. The documentation states that this is the method invocated before calling the Value method in order to get a new value. In fact, in the method implementation we have to write the code that increases the counter value, and also to check if the counter value is over the available quantity of items. That is, we have to add a counter Property to our class, and initialice it with the value -1.
• Value. This is the method that will be called every time we need to get a new value. In our example, this will return a new PostalAddress object from the available items.

Thus, the implementation for the MoveNext method could be the following:

counter = counter + 1

But the method signature and the class interface documentation states that the method has to return a boolean value True if there are remaining available items to iterate, and False when we have surpassed the quantity of iterable items; and in that case we should raise an exception in order to point this out.

For example, our class could check if the counter doesn’t exceed the quantity of items stored by the PostalAddresses Array, returning the corresponding boolean value.

But let’s fill in some holes before writing the final implementation for the MoveNext method. First, let’s add some more needed properties:

• maxPostalAddresses As Integer. This will be responsible for storing the quantity of elements available under the PostalAddress Array.
• source As Person. This will be in charge of saving the reference to the Person object it has to iterate.
• The Calculated Property valid as Boolean. We will use the Get method from this calculated property to know if the PostalAddress Array has been modified during the iteration of the object, returning False when this is the case. In fact, this is the code for the Get
  method:

Return if(source.postalAddresses.Ubound = maxPostalAddresses, True, false)

Next, we will add the Constructor method to the class using this signature:

Constructor( value As Person )

and the following code for the method:

source = value
maxPostalAddresses = value.postalAddresses.Ubound

That is: we initialize the previously declared property’s values with the reference to the Person object that we will use to iterate over, and the quantity of elements included in the Array when we initialize the class; thus, the original items quantity that we will use to check if it has been modified during the iteration process.

Now we can move back to the MoveNext method to write its final implementation:

If valid Then
  counter = counter + 1
  Return If(counter <= source.postalAddresses.Ubound, True, False)
Else
  Dim e As New Xojo.Core.IteratorException
  e.Reason = "Invalid Data"
  Raise e
End If

Inside the method implementation we will check also if the object has been modified during the iteration, returning the corresponding value:

If valid Then
  Return source.postalAddresses(counter)
Else
  Dim e As New Xojo.Core.IteratorException
  e.Reason = "Invalid Data"
  Raise e
End If

As you can see, the Value method will return the PostalAddress item from the Person array, using as Index the value of the Counter property.

Creating the Iterable Class

Now we have to create the iterable class itself. For that we will add a new class to the project usingIterablePerson as its name and making it a subclass from the Person class, so we have to write this data type in the Super field of the Inspector Panel. In addition, this class will be the one that implements the class interface Xojo.Core.Iterable, so you have to push on the Choose button associated with the Interfaces label in order to select and confirm the addition of the corresponding methods. In fact, is just one method:

GetIterator() As Xojo.Core.Iterator

And this is the code you have to write for that method:

Dim it As New iterablePerson(Self)
Return it

With this we have all the definitions we need for the subclass: we get a new IterablePerson instance passing as parameter the iterable object (a Person subclass). That’s all! Finally, we return the iterator we get and that will be used inside the For Each… Next loop.

Putting it all together

Armed with all the needed classes for our example, we can finally put it all into practice. For this, we will use a ListBox in the main project Window (Window1). This is the control where we will add as many rows as postal addresses associated with a instance of the Person class used for the example. For this, add also a button to the window with the Action event and write the following code in the resulting Code Editor:

Dim p As New iterablePerson
p.name = "Juan"
p.middleName = "Sin Miedo"
p.secondName = "De Nada"
Dim d As New PostalAddress
d.street = "Juan de Urbieta"
d.streetNumber = 6
d.streetFlat = 1
p.postalAddresses.Append d
d = new PostalAddress
d.street = "Mi calle bonita"
d.streetNumber = 8
d.streetFlat = 3
p.postalAddresses.Append d
d = new PostalAddress
d.street = "Princesa"
d.streetNumber = 5
d.streetFlat = 5
p.postalAddresses.Append d
For Each s As PostalAddress In p
  Listbox1.AddRow s.street + ", " + s.streetNumber.ToText + " Piso: " + s.streetFlat.ToText
Next

Run the project, push the button and you will see how the For Each… Next loop iterates every postal address associated with the Person object. This is a more concise, stylish and OOP way of doing things when compared with the classic For… Next loop, where we have to get the upper value (or limit) and use a variable as index to get every collection object we are interested in.

For more on this topic:

• Video: Arrays, Dictionaries, Iterators
• User Guide: Iterator and Iterable Interfaces

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 and the Snippery app, among others.

*Read this post in Spanish

• Growing? Read how one Xojo user took his app from in-house to commercial,
• Transitioning Windows Graphics: Direct2D/DirectWrite,
• Remote Debugger for Raspberry Pi and the Programming with Raspberry Pi Book,
• Check out our highly popular JSON Feed blog post series for iOS, web and Desktop,
• We updated Xojo’s Linux Desktop framework to GTK3 and HiDPI,
• Whatever happens, Xojo has your back if Mac goes ARM, and
• Jump into our ongoing Compiler blog post series: LLVM Everywhere, Compiler 101 – Overview and Lexer, and Compilers 102 – Parser.

A special mention on the topic of Net Neutrality in the US. Geoff has shared his point of view and we hope you make your voice heard to the FCC before December 14th. This is an issue that effects us all.

The Xojo community continues to grow with developers switching from VB, emerging citizen developers and small businesses all discovering what they can with Xojo. In the last 12 months the Xojo Forum has welcomed 1,688 new forum members and 60,772 forum posts.

Our blog post from back in June, Daring to Defy Software Extinction sums up Xojo and Dev Tool history with some perspective. We’re proud of what we, along with the Xojo Community, have built over the past 21 years and we look forward to 2018 – Android support, I’m looking at you!

From everyone at Xojo, thank you for your continued support. This community is truly one-of-a-kind and we look forward to all that 2018 has in store!

Use the new Framework, Luke

The Xojo.Core.Date and Xojo.Core.DateInterval classes under the new, Xojo framework make it really easy to get the difference between two given dates. The code you’ll need for this is as easy as this:

Using Xojo.Core
Dim dateA As date = New Date(2017,10,23, TimeZone.current)
Dim dateB As date = New Date(2017,11,23, TimeZone.Current)
Dim result As DateInterval = dateB - dateA
MsgBox result.Years.ToText+ " " + result.Months.ToText + " " + result.Days.ToText

The key here is in the use of the subtract operator that gives as result a TimeInterval instance. Thus, accessing the properties of this instance will get the years, months and days elapsed between the two compared dates. Take into account the importance of the order of your Date operands when used with the subtract operator. I mean, if the rightmost date is higher than the leftmost date, then probably you will get some negative values for the properties. In some cases, this will be the expected behaviour for the logic of your app… other times, you will prefer to check this before getting the DateInterval instance in order to get proper values.

Date difference for existing code

But, what if you want to get the same function for your current code based on the date class? Here you can opt for several options. The one we are going to put in practice is based in the use of the Xojo Module in combination with the Class Extension OOP feature. In fact, Class Extension is the way we can extend the functionallity of an existing Class. Straight, right? So, in order to achieve this the first step, add a new Module to a Xojo project and name it using the Inspector Panel (for example, “Extents”). Then, select the newly created module and add a new Method to it using the following signature:

• Method Name: Difference
• Parameters: Extends d As Date, RightDate As Date
• Return Type: Dictionary

Next, we will add some text constants to the Module, that will be used by the Method and help any calling code that wants to access the result.

• kDay As String = Day
• kDay As String = Month
• kYear As String = Year

Afterwards, select the Difference method and type the following lines of code in the resulting Code Editor:

Dim difference As Double = RightDate.TotalSeconds - d.TotalSeconds
Dim days As Integer
Dim years As Integer
Dim months As Integer
Dim dateResult As New date
dateResult.TotalSeconds = difference
days = dateResult.Day - 1
years = dateResult.Year - 1904
months = dateResult.Month - 1
Dim result As New Dictionary
result.Value(kDay) = days
result.Value(kYear) = years
result.Value(kMonth) = months
Return result

As you can see, the code is simple enough. In order to simplify the code to a maximum, this example opts to give the result as an Instance of Dictionary and using the previously definied constant to store the “Year”, “Months” and “Days” of difference between the compared dates. If you want, you can use an additional Structure or Class to return the result (your own DateInterval?).

To test the new Class Extension, add an Open Event to the Window or App object of your project and type this lines of code:

Dim d As New date(2017,10,24)
Dim d1 As New date(2017,11,30)
Dim interval As Dictionary = d.Difference(d1)
MsgBox interval.Value(kYear) + " " + interval.Value(kMonth) + " " + interval.value(kDay)

A new Date Class that makes the Difference

There is a third option that we can explore that is more OOP oriented: create our own Date class and implement the subtract operator on it. More or less the thing that we do when using Xojo.Core.Date.

For that, the first step is adding a new class to a Xojo Project (Insert > Class). Use the following data in the Inspector Panel:

• Name: MyDateClass
• Super: Date

Next, add to the class the same constant we defined in the previous section (kDay, kMonth and kYear). These will be used to define the keys in the resulting dictionary and to ease operations from the calling code too.

The most important thing is adding a new Method to our class with the following data:

• Method Name: Operator_Subtract
• Parameters: rightMostDate as Date
• Return Type: Dictionary

The Operator_Subtract method instructs the Xojo compiler so you can use the minus sign (-) between two instances of the class. Type these lines of code for the method:

Dim difference As Double = self.TotalSeconds - rightMostDate.TotalSeconds

Dim days As Integer
Dim years As Integer
Dim months As Integer

Dim dateResult As New date

dateResult.TotalSeconds = difference

days = dateResult.Day - 1
years = dateResult.Year - 1904
months = dateResult.Month - 1

Dim result As New Dictionary

result.Value(kDay) = days
result.Value(kYear) = years
result.Value(kMonth) = months

Return result

Then in the Open Event of a Window, or the App object, check the class with the following code:

Dim d2 As New MyDateClass(2017,10,24)
Dim d3 As New MyDateClass(2017,11,30)

interval = d3 - d2

MsgBox interval.Value(kYear) + " " + interval.Value(kMonth) + " " + interval.value(kDay)

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 and the Snippery app, among others.

*Read this post in Spanish

This post was updated in 2021 to using Xojo’s API 2.0.

There are plenty of times when your Xojo apps might need to know what the public or external IP address in use is, and for that there are a lot of web sites or services that you can use from Xojo. Nevertheless, I found ipify to be the simplest and easiest to use, plus it is highly available due to being hosted by Heroku. That means, for example, that if half the Internet is down…you still can be confident to reach the ipify service in order to get the information.

Using ipify from a Xojo desktop apps is as simple as using this code:

Dim request as New HTTPSSocket
Dim s as String = request.get("https://api.ipify.org",10)

But sometimes we need additional information, for example knowing if the IP address has changed over time, or simply checking periodically for IP address changes. And that is something that you can find in the OpenSource project ipify for Xojo available in this repository from GitHub.

ipify for Xojo is designed as a Singleton class, what means that you even don’t need to instatiate it in order to get the current IP address, know if the IP has changed over time, or even instruct the class to periodically check for the IP address, notifying the registered object every time with the current IP address in use and if it is the same or has changed from the last checking.

Download IPify for Xojo from GitHub

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 and the Snippery app, among others.

*Read this post in Spanish

All the methods related to cryptography and data ciphering are available under the Crypto module of Xojo, using behind the scene the Crypto++ 5.6.3 library. From the practical side, this allows us to use the RSA public key ciphering and other algorithms to compute unique footprints for given data, as for example Hash, MD5 or SHA. Paul blogged about using Public/Private Key Encryption in Xojo back when we added RSA encryption functions in 2014.

Among the methods related to RSA, we can find the ones to create the Private/Public keys, test the integrity of the public key, signing the given data and, of course, check the integrity of the signature, and ciphering / deciphering the given group of data.

As you probably already know, when we work with RSA we have to keep the Private key in a safe place, using the Public one to give to other people/service/app to whom we want to share information with in a safe manner. This way the users and/or apps and services will be able to use our public key to cipher the data that they want to share with us, and we will be able to use our private key to decipher that group of data so it is legible again.

RSA: Creating and interchanging the keys

Generating the pair of keys could not be more easy in Xojo, with this snippet of code:

Dim publicKey As String
Dim privateKey As String
If Crypto.RSAGenerateKeyPair( 1024, privateKey, publicKey ) Then msgBox “Successfully generated Keys!"

As you can see, the RSAGenerateKeyPair method receives the Integer number that indicates the strength (robustness) of the generated keys, followed by the String variables containing the generated Private and Public keys, passed by reference.

But in some cases it is possible that you want to use these keys beyond the scope of Xojo, for example when integrating your app with a service or solution developed in PHP. In these cases you have to consider that the keys generated with Xojo are in hexadecimal format.

What does this mean? Well, a public key generated with Xojo will look like this chunk of data:

30819D300D06092A864886F70D010101050003818B0030818702818100B4B531D3402C250D8640E739601F01FBE8ABB39635BE1778A7F4E55C49419C0595EF5A5824EA8E7A1871FB63B8960EDBB97B08C2E7EA43229903AEBCB45B9FD9E24780B15BCADB5E026849592CC1FA9B399EBD8457CC4E7A686CF53E9146E1D867ACEB675728E8821DEDA4C2F807FD668A81601F551484C5D1334B62D5E90E33020111

While other external libraries (as is the case in most of the web development frameworks), expect other data format codified as Base64. This is, something like this:

-----BEGIN PUBLIC KEY-----

MIGHAoGBALS1MdNALCUNhkDnOWAfAfvoq7OWNb4XeKf05VxJQZwFle9aWCTqjnoYcftjuJYO27l7
CMLn6kMimQOuvLRbn9niR4CxW8rbXgJoSVkswfqbOZ69hFfMTnpobPU+kUbh2Ges62dXKOiCHe2k
wvgH/WaKgWAfVRSExdEzS2LV6Q4zAgER

-----END PUBLIC KEY-----

So the first step to encode our Xojo keys (Public or Private ones) as Base64 is converting them previously from his hexadecimal form to the DER encoding (Distinguished Encoding Rules). Here is where we have to employ the DEREncodePrivateKey and DEREncodePublicKey methods if we want to encode the Private or the Public key, respectively. Once we have done this, we will be able to encode the resulting chunk of data as Base64 without forgetting to add the header “—–BEGIN PUBLIC KEY—–“ and the footer “—–END PUBLIC KEY—–“ with the accompanying ends of lines, or maybe the header “—–BEGIN CERTIFICATE—–” and the footer “—–END CERTIFICATE—–“ if we are dealing with a Public Key (for the Private keys we have to use the header “—–BEGIN RSA PRIVATE KEY—–” and the footer “—–END RSA PRIVATE KEY—–“).

You can interchange and use the Private and Public keys generated with Xojo using the PHPSecLib library.

In addition, as pointed by Thom McGrath, you can use also these keys with OpenSSL this way:

if (@openssl_public_encrypt($data, $result, $public_key, OPENSSL_PKCS1_OAEP_PADDING)) {
         return $result;
 } else {
         throw new \Exception('Unable to encrypt');
 }

Xojo’s Crypto library will be able to use a private key to decrypt $result in this case.

Finally, if you are interested in the cryptography topic, let me recommend you some good books: Applied Cryptography and Cryptography Engineering.

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 and the Snippery app, among others.

The following tutorial is based on the Desktop Xojo project that you can download from this link. In fact, this project was the foundation to the search filed control implemented in the Snippery app. Thus, you can envision in more detail the kind of functionality you can achieve when used in a real app. Ok, maybe you are thinking “this is not the native control a user expects when using a true native app under certain OS”. That’s true; anyway there are a lot of apps around (some of them from the big players) that use non-native controls in favour of providing a unified UI between all supported platforms. This is the case of the final class exposed here, offering the same aspect and behaviour when running under macOS, Windows and Linux.

Preparing the Ingredients

In order to create our multiplatform search control we need to use a series of components (classes) that will cooperate with each other: a TextField that will receive the user keyboard input (that is, where the user inputs the text to search); a Canvas subclass to display the typical magnifying glass icon and other decoration for the control (that also extends further to add more functionality); and a second Canvas subclass that will offer the classic “search text clean” widget functionality normally presented at the right of a search field.

Of course, you can create a search field using these classes as individual items on a Window layout, but in that case all the resizing operations and cooperation between the controls will be more messy — losing the encapsulation that a ContainerControl provides to the other components of the application as if it was a unique, simple control.

Dealing with the Graphics

The resulting control uses three pictures for a total of two functions: one for the magnifying glass and two for the “text cleaning” widget that will be displayed only when the TextField has text on it. The widget has to change its image when the pointer is on it so the user can see that this is an active “clickable” control.

Fortunately Xojo eases the management of multiresolution pictures in our apps, changing on the fly between the existing regular/normal resolution and the HiDPI/Retina versions for the same given picture. Thus, we only need to use our favourite graphics editor app to draw and export the pictures with the required quality as PNG files (personally I use the Sketch on macOS).

In order for Xojo to be able to do its magic, you shouldn’t import the pictures to the app by dragging them from disk and dropping them on the Project Browser or Xojo will import the pictures as an alias. Instead, use the Insert > Image option to add an Image instance to the project, showing the associated Editor where you’ll be able to assign every picture file for the supported resolutions of a same graphic. Of course the label you use as the Image name on the Inspector Panel will be the name you use to reference the Image from code or when assigned to other controls properties. If you explore the example project for this tutorial, you can see the three Images used: searchIcon, CloseSelected and Close in regular and HiDPI/Retina resolutions.

Creating the Text Cleaning Widget

We have already seen in a previous tutorial (in Spanish) how easy it is to create custom graphic controls in Xojo based on the Canvas Class. In order to create the widget providing the search text cleaning feature, we will follow that same principle here:

• Add a Canvas subclass and name it CloseButtonClean.
• Add the Open, MouseEnter and MouseExit events to the subclass
• Type the following code into the Open event, basically to assign the picture showing its initial state and making it invisible:

me.Backdrop = close
me.Visible = false

• We will use the MouseEnter and MouseExit events to change the displayed picture in response to  the pointer cursor being inside or outside the limits of the control; showing that this is an active/clickable control. Put the following line of code in the MouseEnter event:

me.Backdrop = CloseSelected

• And the following one in the MouseExit event of the control:

me.Backdrop = close

We have completed the decoration of our little class, but it is also desirable to provide an external interface so other controls can easily change the state of the widget. We will do that by adding two methods to the class.

With the widget class still selected on the Project Browser, select the Insert > Method option twice to add two Methods and using the Inspector Panel to change the Method names to “Activate” and “Deactivate”, respectively. Leave the Scope as Public for both methods, so they are reachable by other objects and not only those created from the class.

The select method simply changes the control visibility to True:

me.Visible = true

While the Deactivate method will do the opposite action:

me.Visible = false
me.Backdrop = Close

Drawing the Search Control

The second of the required classes based on the Canvas class is no more complex. In this case we will not assign a picture to the Backdrop property of the Canvas, instead we will use the Paint event to directly draw the decoration, including the magnifying glass picture at the appropriate coordinates of the control.

So, after adding a second Canvas subclass to the project —named cSearchBackground in our Example project—, we just need to add the Paint event to it, writing the following lines of code on the associated Code Editor:

g.PenWidth = 1
g.PenWidth = 1
g.ForeColor = &caaaaaa
g.DrawRoundRect(0,0,g.Width,g.Height,5,5)
g.ForeColor = &cffffff
g.FillRoundRect(1,1,g.Width-2, g.Height-2,5,5)
dim midY as integer = (g.Height/2) - (searchIcon.Graphics.Height/2)
g.DrawPicture(searchIcon,5,midy)

In essence, we are drawing the control border using the provided foreground color (&caaaaaa, in hex notation), and filling the control background with the white color. After that, we will paint the magnifying glass icon using the DrawPicture method of the Graphic class provided as the drawing context for the Paint event.

Container Control: Putting it all Together

Once we have all the required items for our “complex” UI control, it’s time to add a ContainerControl to the project using the Insert > ContainerControl option. The first thing you probably notice is that the Layout Editor is very similar to the one used for designing the windows of the app. After all, the ContainerControl is about adding, resizing and aligning several UI controls on it, as you do when designing a window.

With the added ContainerControl still selected, change the attribute Name to ContainerSearchField on the associated Inspector Panel.

Now we just need to add an instance of our cSearchBackground class to the ContainerControl, a TextField control from the Xojo Library Panel and our search text cancelation widget class to the right of the just added TextField. The final layout of the control should be something similar to this (after adjusting the own Container Control height and width):

In order to correctly draw the control background when resizing the ContainerControl, select the cSearchBackground instance and add the Open event with the following line of code:

me.Width = self.Width

In addition, we also want that the TextField to show our search text cancellation widget only if the TextField has text on it. Select the TextField instance on the ContainerControl (searchField in the example project), and add the TextChange event with the following code in the associated Code Editor:

if me.Text <> "" then
  CloseButtonClean1.activate
else
  CloseButtonClean1.deactivate
end if

With the TextField still selected, set the CueText property under the Initial State section of the Inspector Panel to “Search”. This will be the text shown by default when the TextField is empty.

Of course we want to add functionality to the instance of our search text cancelation widget —named CloseButtonClean1 in the example project—. Add the MouseDown event and write the following line of code on the associated Code Editor:

searchField.Text = ""

When using a ContainerControl you will want to provide a way to resize every control inside of it in response to the resizing of the ContainerControl itself. We resolve this by adding the doResize method to our Container Control with the following code:

closeButtonClean1.Left = me.Width - 24

searchField.Width = (Me.Width - 27) - searchField.Left

cSearchBackground1.Width = me.Width

cSearchBackground1.Invalidate

As you can see this method simply does some calculations to reposition the controls based on their relative coordinates, updating also the width of the background control to reflect the same width of the ContainerControl itself. Finally it calls the invalidate method on the background instance class so the control can update the drawing.

In order to finish our ContainerControl subclass, we just need to add a couple of events: Open and Resizing. The first will be in charge of setting the initial state for the control, while the second will call the doResize method every time the ContainerControl is resized.

Once you’ve added these events, select them and simply write the call to the doResize method in both cases.

Using the SearchField ContainerControl

That’s all! You can start using the control by dragging it from the project browser to the Window Layout in order to create a new instance. Of course, we have not implemented the search functionality itself in this example project, mainly because it depends of the purpose of the final application itself. In addition, it would be easy for you to add extra functionality as text autocompletion as we have seen in a previous tutorial.

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 and the Snippery app, among others.

*Read this post in Spanish

*Watch the video in Spanish

The Raspberry Pi is a complete computer —and a very cheap one!— with USB, HDMI, Ethernet and a GPIO that gives the access to design, create, and control a lot of things (think IoT). The perfect combination to create and deploy complete solutions with Xojo.

Nevertheless, you probably don’t want to use an exclusive display, keyboard and mouse just to control and interact with your Raspberry Pi. What about accessing it remotely via SSH and/or VNC? I bet this is the first thought you had, and here is a step-by-step guide to configure it so you can use your current display, keyboard and mouse from you main computer (the one you use to run the Xojo IDE) to control the Raspberry Pi.

First of all, while you can access your RPi via SSH, displaying your well trained Geek super powers, it is really more convenient to control it via the GUI, as you do your computer. For that you’ll need a VNC client app. There are a lot out there, but VNC Viewer is one that runs just fine and is available for the main platforms. Just download it, run the installer, follow the steps… and you will have completed the first part of the process.

In order to access the Raspberry Pi from the VNC client you will need to know what IP address is using the Pi. How to get that information? Easy! (This assumes that your local network uses DHCP to assign IP addresses, the most common scenario.)

If you use macOS, open the Terminal app (Applications > Terminal) and run the command:

$ ping 192.168.1.255

Changing the ‘192.168.1’ part of the IP address for the one of your local network. What is important here is the ‘255’ number, because this is the Broadcast IP address for your local network.

What happens when we ping the broadcast address? In brief: the packets are sent to every host of the local area so they can respond, giving their IP address in the process. The second piece of the needed information, the MAC Address, is automatically obtained from the hardware interface used by the device to reply the packet request.

Let the ping command do its work for several seconds and break the process pressing Control + C. (If you are using Linux, execute the command as ‘ping -b xxx.xxx.xxx.255‘.

The Mac Address is all the information needed by ARP: the inner cache table used by your router/switch device (and computer too), to link the unique hardware address (MAC Address) used by every device in the network with the IP address used by the device. So, executing the command:

$ arp -a

will give us a complete list of evey active IP address and the linked MAC Address. Knowing what IP addresses are already used by the devices of our network (computers, printers, cell phones, tablets…), it will be easy to identify the IP address assigned by DHCP to the Raspberry Pi.

So with these two pieces of information you can use the DHCP Binding feature of your home switch/router (all the home/SOHO routers have this feature), in order to assign the same IP address to the Raspberry PI every time you turn the device on and, connect it to the network. DHCP Binding looks for the MAC Address of the device… and matches it with the reserved IP address from the DHCP pool.

Starting the VNC Server on the Raspberry Pi

Don’t close the Terminal window yet, there are a couple of things that we need to do first. The first one is starting the VNC Server on the Raspberry Pi, so we can start new remote sessions from our client. For that we need to start an SSH session with:

$ ssh pi@raspberry-pi-address-here

Typing ‘raspberry’ as the password when requested. (‘pi’ and ‘raspbery’ are the user and password configured by default on every Raspberry Pi out there.)

Once started the SSH session, type the following:

pi@raspberrypi:~$ sudo raspi-config

This will open the Configuration Tool. Use the cursor keys to choose the ‘Advanced Options’ entry and press the Return key to advance to a new screen with options. Select the VNC entry (A5) and press the Return key again. Finally, make sure that VNC Server is enabled or enable it if not. Lastly, select the <Finish> option to exit the Configuration Tool.

Adjusting the Display Resolution used by VNC

Great, we have the IP address used by the Raspberry Pi, and the VNC Server enabled so we can start a VNC Client session… just to discover that it shows an endemic resolution of 800 x 600 pixels on our full-fledged Full HD display. Not the most productive thing we can expect.

Time to return to our Terminal windows, where the SSH session is still open (or start a new one if not). This time, we will edit the configuration file to instruct the Raspberry Pi to use a better fixed display resolution. For that, type the command:

pi@raspberrypi:~$ sudo nano /boot/config.txt

Go to the end of the opened file and write these lines:

 hdmi_force_hotplug=1
 hdmi_ignore_edid=0xa5000080
 hdmi_group=2
 hdmi_mode=51

In this case we are telling the Raspberry Pi to use a resolution of 1.600 x 1.200 pixels, but you can choose other changing the ‘hdmi_mode’ option to anyone of the settings you can find in this support page of Raspberry Pi.

Save the changes and exit from the Nano editor, and reboot the Raspberry Pi so the changes take effect:

 pi@raspberrypi:~$ sudo su
 pi@raspberrypi:~$ reboot

Ready! From now on, you can remotely access your Raspberry Pi via VNC and SSH.

You can watch the video (in Spanish only) that talks you though this example.

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

*Read this post in Spanish

The Singleton and Observer Design Patterns have been described in previous blog entries and I highly recommend to read them now so you can get the flavor of the fundamentals behind them. I’ll wait here for you, I promise! Then we will deal with the code that varies to implement our NotificationCenter class, and to put it in practice with a Desktop example project.

Of course, before of continuing reading, you can download the example project, run it and review the code to get a first glance of what it does and how it works. Then, you can come back and continue reading if you want to better understand the NotificationCenter class inner, or how other objects can use this class.

The NotificationCenter Class

Execute the Xojo IDE and create a new Desktop project. Add a new class using Insert > Class. Go to the Inspector and change the Name attribute to “NotificationCenter”. This is the name of the new class we are designing (and, thus, a new Data Type).

With the new class still selected in the Navigator (the leftmost column on the Xojo IDE), add a new Shared Property (Insert > Shared Property). Use the Inspector again to change the Name attribute to “Instance”, the Type field to “NotificationCenter” and the Scope to “Private”. (You know, a Shared Property or Shared Method are those that you can access from the class itself, without needing to create previously a new instance from the class.)

Add a second Property to the class, this time via Insert > Property (this is, an instance property). Use this values on the associated Inspector:

• Name: Objects
• Type: Xojo.Core.Dictionary
• Scope: Private

Next, add a new Method (Insert > Method). Use the Inspector to choose the Constructor option from the “Method Name” dropdown menu, and set the method Scope to Private.

Write the following code on the associated Code Editor for the method:

Objects = new xojo.core.Dictionary

Defining the Constructor method with a Private scope prohibits the creation of several instances from the class. Instead of that, the class consumers will have to use the convenience method defined by us in order to retrieve the same —and unique— instance for all the cases.

So, now we will add a new Shared Method using Insert > Shared Method. Use the Inspector to put the following values on the created method:

• Name: SharedInstance
• Return Type: NotificationCenter

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

if instance = nil then instance = new NotificationCenter
Return instance

These are the wires to write our Singleton class and to define our Data Model: the “Objects” property of data type Xojo.Core.Dictionary. This property will be responsible for storing the registered objects as observers of the desired Control(s), as well as the messages for whom it is interested in receiving notifications for the observed object(s). Probably this is better understood in the following figure:

That is, the “Observers” Xojo.Core.Dictionary Property uses as Key any object of RectControl data type (the observed object). The associated value for that key is a new Xojo.Core.Dictionary, whose entries will use as Key the Notification (message as Text data type) for what an object wants to register as observer for such Control.

This way, one same object can be registered to several controls and also to several messages (Notifications) on one or several controls.

Finally, the associated value for every Key on this second Xojo.Core.Dictionary is an Array data type whose items are instances of the NotificationReceiver data type.

I know, I know… Stop. Breathe. Execute again the example project. Review the code on the “Register” method to get a better grasp… and back to follow!

Registering Observers

With the class still selected on the Navigator, add a new method (Insert > Method) using the following values. This is the method responsible for registering the new observers on the shared Notification Center instance:

• Name: Register
• Parameters: sourceControl as NotificationReceiver, observedObject as RectControl, message as Text
• Scope: Public

As you can see in “Parameters”, the first parameter is the Observer object (this is the interesed object in receiving the notifications); the second parameter is the observed object (that is from which we want to receive notifications); and the third parameter is the message from which we are interested in receiving the notifications by the observed object.

Write the following code on the Code Editor associated for this method:

dim observedObjects as xojo.Core.Dictionary = Objects.Lookup( observedObject, new xojo.core.Dictionary )
dim messages() as NotificationReceiver
if observedObjects.HasKey( message ) then messages = observedObjects.Value( message )
messages.Append sourceControl
observedObjects.Value( message) = messages
objects.Value( observedObject ) = observedObjects

Sending Notifications

Now is time to add to the class the method responsible to send the notifications to those objects interested in receiving them from any previously registered object. Insert a new method for the NotificationCenter class and use the following values in the associated Inspector:

• Name: sendNotification
• Parameters: sourceObject as RectControl, message as text, value as Auto
• Scope: Public

And the following code in the Code Editor associated with the method:

dim observedObjects as xojo.Core.Dictionary = objects.Lookup(sourceObject, nil)
if observedObjects <> nil then
  dim sourceObjects() as NotificationReceiver
  if observedObjects.haskey(message) then sourceObjects = observedObjects.Value( message )
  for n as integer = 0 to sourceObjects.Ubound
    dim target as NotificationReceiver = sourceObjects(n)
    target.valueReceived( value, message )
  next
end if

As you can see, the first parameter of the method is the control that wants to send a notification (second parameter) to all the possible registered objects, passing the value that such objects can be interested to receive for processing it (third parameter).

Stop receiving Notifications

However, it is probable that one object wants to stop receiving notifications from any previously registered control. For that, we need to add a new method to the NotificationCenter class using this values:

• Name: RemoveObserver
• Parameters: sourceControl as NotificationReceiver

And the following code on the associated Code Editor:

for each observedObjects as xojo.Core.DictionaryEntry in objects
  dim d as xojo.Core.Dictionary = objects.Value(observedObjects.Key)
  for each messagesForObject as xojo.Core.DictionaryEntry in d
    dim sourceObjects() as NotificationReceiver = d.Value(messagesForObject.Key)
    for n as integer = sourceObjects.Ubound DownTo 0
      if sourceObjects(n) = sourceControl then sourceObjects.Remove(n)
    next
  next
next

Stop receiving some Notifications

It may also be the case that one object wants to unsuscribe from the Notification Center to stop receiving just one particular notification. For that, add a new method and use the following values on the Inspector:

• Name: removeObserverForMessage
• Parameters: sourceControl as NotificationReceiver, message as text

And write the following code in the associated Code Editor:

for each observedObjects as xojo.Core.DictionaryEntry in objects
  dim d as xojo.Core.Dictionary = objects.Value(observedObjects.Key)
  for each messagesForObject as xojo.Core.DictionaryEntry in d
    if messagesForObject.Key = message then
      dim sourceObjects() as NotificationReceiver = d.Value(messagesForObject.Key)
      for n as integer = sourceObjects.Ubound DownTo 0
        if sourceObjects(n) = sourceControl then sourceObjects.Remove(n)
      next
    end if
  next
next

One Class Interface that runs them all: NotificationReceiver

Along the implementation of our Notification Center class we have seen several times the reference to the NotificationReceiver data type. This is what we are going to get our hands on next.

In fact this is a Class Interface; what means that it works as a “glue” in order that any object can implement their defined methods. This way the objects can be seen as their native class and also as an instance from NotificationReceiver, so they can be registered as observers on the Notification Center independently the native class they are based on.

Use Insert > Class Interface to add a new Class Interface to the project. Next, write the following values in the associated Inspector:

• Name: NotificationReceiver

With the Class Interface still selected in the Navigator, add a new method using the following signature in the Inspector:

• Method Name: valueReceived
• Parameters: value as Auto, message as Text

Done! Depending on your own needs, you can add more methods for the interface class in combination with the Notification Center class itself.

Testing the Notification Center

Now it is time to design the user interface in order to test the Notification Center class. The changes made on a TextField control will automatically update the contents of a Label control, a Slider control, a ListBox control and a Canvas control. Moreover, the Label instance will subscribe in the Notification Center to receive two types of notifications, changing his behaviour (the text shown) based on the received notification.

We will also add a couple of CheckBox controls to test the functionality to unsuscribe the Label control from all or just some notifications.

But before we start with that, and as we have seen in the previous step, we need that all the objects that want to be able to register on the Notification Center be of the NotificationReceiver data type. That means that we need to create our own subclases for the Label, Slider, ListBox and Canvas controles. Let’s start with the Label!

Label Subclass

Create a new sublcass for the Label Class. You can do that selecting the Label control from the Library and choosing the “New Subclass” option from the contextual menu; or you can drag and drop the control from the Library to the Navigator. Anyway, the result will be the same: you will have created a new subclass with the name “CustomLabel” (it can vary, depending the Xojo release you use). By the way, you also can use Insert > Class in order to create a new subclass.

Regardless of the method used to create the new subclass, choose it in the Navigator and use this values in the associated Inspector:

• Name: MyLabel
• Super: Label // This way, our sublcass will inherit all the methods, events and properties from the base class.
• Interfaces: Click on the button and choose “NotificationReceived” from the resulting panel/Window. Confirm the selection clicking on the “OK” button.

As result of the last action, Xojo will automatically added the ValueReceived method to the class. Write the following code in the associated Code Editor:

RaiseEvent newValueReceived value, message

Here we raise a new event (not defined yet), so every instance from the class can be in charge of implement the real behavior in base of the parameters received.

So, with the “MyLabel” class still selected, use Insert > Event Definition to add the event definition we need. Use the following values in the associated Inspector:

• Event Name: newValueReceived
• Parameters: value as auto, message as Text

Slider Subclass

Add a new subclass and use these values in the associated Inspector:

• Name: MySlider
• Super: Slider
• Interfaces: Add the NotificationReceiver Class Interface as seen in the previous step.

Write the following code for the ValueReceived method:

RaiseEvent newValueReceived val(value)

And add the event definition using Insert > Event Definition, as we have seen in the previous step. Use this signature in the Inspector:

• Event Name: newValueReceived
• Parameters: value as integer

ListBox Subclass

Let’s create now the subclass for the ListBox, following basically the same steps already done with the previous subclasses. Use the following values:

• Name: MyListBox
• Super: ListBox
• Interfaces: NotificationReceiver

Write the following code in the Code Editor associated with the ValueReceived method added by the Class Interface:

RaiseEvent newValueReceived val(value)

And add the corresponding Event Definition using this signature:

• Event Name: newValueReceived
• Parameters: value as integer

Canvas Subclass

We have arrived to the last subclass definition for our example project. Add a new subclass to the project and use this values in the associated Inspector:

• Name: MyCanvas
• Super: Canvas
• Interfaces: NotificationReceiver

Write the following code for the ValueReceived method:

dim s as string = value
newValue = s.ToText
me.Refresh

Next, use Insert > Event Handler to add the Paint event to the subclass. Write this code in the associated Code Editor:

dim size as integer = val(newValue)
g.TextSize = size
dim centerx as integer = g.Width/2 - g.StringWidth(newValue)/2
dim centery as integer = g.Height/2+g.StringHeight(newValue,g.Width)/2
g.ForeColor = rgb(size, size, size)
g.FillRect(0,0,g.Width,g.Height)
g.ForeColor = if(size <= 50, rgb(255,255,255), rgb(0,0,0))
g.DrawString(newValue,centerx,centery)

Lastly, add a new property to the subclass using Insert > Property, and using this values:

• Name: newValue
• Type: Text
• Scope: Private

Designing the User Interface

Once we have created the subclasses for the Controls we will use as observers in our example app, it is time to design the user interface. For that, choose the window by default for the project (Window1).

Xojo will show the Layout Designer for the selected Window. Drag the subclass controls from the Navigator (or from the Library) so they are arranged as shown in this picture. In addition, drag a couple of CheckBox controls and one TextField too from the Library to the layout.

Choose the label instance (with the name “Label2” in the example project) and use Insert > Event Handler to add the “newValueReceived” event handler previously defined in our class. Write the following code in the associated Code Editor:

dim s as string = value
Select case message
  case "valueChanged"
    me.Text = "Value on source Control: "+ s
  case "charValue"
    me.Text = "ASCII Code for last keystroke: "+ str(asc(s))
End Select

As you can see, the event uses the received message to decide how to work with the value sent by the observed object. In one case it will show the value as is, and for the other it will show the ASCII code for the value received as Text.

Select now the Slider instance (with the name “Slider1” in the example project), and repeat the action to add the Event Handler “newValueReceived” to the control. Write the following code in the associated Code Editor:

me.Value = value

In this case, the control will simply assign to his “value” property the value received.

Select now the ListBox instance (“ListBox1” in the example project). Add the Event Handler “newValueReceived” and write this line of code:

me.ListIndex = value

We will also add the “Open” Event Handler, so we can populate some default values to use in the example. Once we’ve added this event, write the following code in the associated Code Editor:

for n as integer = 0 to 99
  me.AddRow str(n)
next

Lastly, select the TextField instance (“TextField1” in the example project), and add the “Keydown” and “Lost Focus” Event Handlers. Once added, select the KeyDown event handler and write the following code:

dim myNotificationCenter as NotificationCenter = NotificationCenter.sharedInstance
myNotificationCenter.sendNotification(me,"charValue",key)

Next, select the LostFocus event and writhe the following code:

dim myNotificationCenter as NotificationCenter = NotificationCenter.sharedInstance
mynotificationcenter.sendNotification(me,"valueChanged",me.Text)

For both cases, we retrieve the shared instance from the Notification Center class and publish a new notification, passing along the own control as first argument (acting as originator), the message or published notification as second argument, and the value sent as the third argument. From this point on, the Notification Center will be in charge of propagate the received notification to all the interested objects.

Subscribing and Unsubscribing to Notifications

Let’s get in charge of the user interface controls whose function is to enable and disable the notifications for our MyLabel instance (Label1).

Select the CheckBox1 control, add the Action event handler and write the following code in the associated Code Editor:

dim miNotificationCenter as NotificationCenter = NotificationCenter.sharedInstance
select case me.Value
  case true
    miNotificationCenter.register(Label2,TextField1, "valueChanged")
    miNotificationCenter.register(Label2, TextField1, "charValue")
  case False
    miNotificationCenter.removeObserver(Label2)
    CheckBox2.value = false
end select

Select now the CheckBox2 control, add the Action event handler and write the following code:

dim miNotificationCenter as NotificationCenter = NotificationCenter.sharedInstance
select case me.Value
  case true
    miNotificationCenter.register(Label2,TextField1, "valueChanged")
  case False
    miNotificationCenter.removeObserverForMessage(Label2,"valueChanged")
end select

As you can see, in the first block of code we register the “Label2” control so it can receive both notifications when the checkbox value is True, and unsubscribe the control from receiving any notification when the checkbox is False. For the second block of code, the “Label2” control just subscribe or unsubscribe for one of the two notifications, respectively.

Starting engines!

What we need to put all to work? Add the Open event handler to “Window1” and write the following code.

dim miNotificationCenter as NotificationCenter = NotificationCenter.sharedInstance
miNotificationCenter.register(Label2,TextField1, "valueChanged")
miNotificationCenter.register(Label2, TextField1, "charValue")
miNotificationCenter.register(Listbox1,TextField1, "valueChanged")
miNotificationCenter.register(Slider1,TextField1, "valueChanged")
miNotificationCenter.register(canvas1,TextField1, "valueChanged")

This code will register the interested controls (observers) to the Notification Center for those Notifications they are interested in. Of course, this can also be done inside the Open event handler for every interested control!

In brief

As we have seen, with the combination of the Observer and Singleton Design Patterns, and the help of one Class Interface definition, we have created our own Notification Center from scratch to greatly automatice and simplify the communication between the objects, their processes and easying also the maintenance and extension of the app functionallity.

You can watch the video (in Spanish only) that talks you though this example.

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

*Read this post in Spanish

Creating the Class Interface

Our Xojo project will use three main items: a subclass from the TextField class, a Class Interface definition, and a Class that will do the job of the Dictionary containing the suggested words for the Autocomplete feature and that will conform to the Class Interface. This way, you’ll be able to use any object as the Dictionary source, as long as it conforms to the expected Class Interface.

Note: The Dictionary referred to here is not the Xojo Dictionary class, but is our collection of suggested words for use by autocomplete.

In fact let’s start creating a Class Interface; so run the Xojo IDE and create a new Desktop project.

1. Add a new Class Interface to the project selecting Insert > Class Interface.
2. Write ‘TextAutocompleteSource” in the Name field of the Inspector. This one will be the Data Type for the created Class Interface.
3. Select the icon for the ‘TextAutocompleteSource’ in the Navigator (the leftmost column in the IDE Window), open the contextual menu and choose the ‘Add to “TextAutocompleteSource” > Method’ option. This action will bring us to the Inspector, so we can define the new Method signature.
4. The first of the methods will be in charge of adding a new word to the dictionary, so use ‘AddWordToDictionary’ as the Method Name, and type ‘Value As String’ in the Parameters field.
5. Add a second Method, name it ‘Match’, type ‘Value As String’ in the Parameters field, and ‘String’ for the ‘Return Type’ field. This will be the invoked method in order to find and return a word suggested for the received string.

That’s all we need for our Class Interface. Simple, isn’t? Remember that Class Interfaces just deal with Method definitions, and the classes that conform to it will be responsible for implementing the code for the methods.

Defining our Dictionary

Now is time to create a new class that will play the role of the main Dictionary for the app of this Tutorial. This one will implement, in fact, the Class Interface defined in the previous section. This means that will implement the real functionality for the methods defined in the TextAutocompleteSource Class Interface.

• Create a new Class selecting Insert > Class from the main Toolbar or from the Insert menu.
• Type ‘StringStack’ in the Inspector as the name of the new Class. This will be the name for the just created Data Type.
• From the Inspector, click on the Choose button near to the ‘Interfaces’ label. As a result, this action will open a new Window showing all the available Class Interfaces… including the one created by us in the previous section! Select this one (TextAutocompleteSource) and confirm the selection clicking the ‘OK’ button.

• As result, Xojo will add the methods declared in the selected Class Interface. We will implement the code for these two methods in a later step.

• Add a new Property to the class: with StringBack selected, choose Insert > Property. In the resulting Inspector, type ‘Collector(-1)’ in the Name field. This means, that our Property will be an Empty Array. Type ‘String’ for the ‘Type’ field and choose ‘Private’ as the Scope for the property.
• Let’s implement the code for the Class Interface methods! Select the ‘addWordToDictionary’ method and type the following code in the associated Code Editor:

if not Value.IsEmpty then Collector.Addrow(Value)

Select now the ‘Match’ method and type the following code in the associated Code Editor:

Var n As Integer = Value.Length
Var t As String
For Each item As String In Collector
  t = element.Middle(0, n)
  if t = Value then return item
Next
Return ""

This method is the one responsible to find a suggested word for the received string. Probably you’ll want to improve the algorithm in your own implementation (depending mainly on the kind of object you will use as a Dictionary), but this one will serve for our testing app.

Adding a Constructor to the Class

Now we are going to define a very special method to the Class: the Constructor. When a Class has this method it will execute the code from this method every time we create a new instance (object) from the Class. Usually we use the class Constructor (you can have several of them thanks to the OOP feature of Method Overloading) to define the initial state of the new instantiated object. In our case, we will use the Constructor to assign the initial state of the dictionary (the Collector property we’ve defined in a previous step) during the instantiation of the object.

1. Add a new method to the Class (Insert > Method). Next, select the ‘Constructor’ item from the ‘Method Name’ drop-down menu or type it.
2. As we would do with a regular Method, we can modify the Constructor method signature to define, for example, the amount and type of the parameters. In fact, for our Constructor we will type ‘Value() As String’ for the Parameters field.

Add the following code to it:

Collector = Value

Subclassing: TextField Specialization

We have finished the auxiliary items needed for the project, so it is time to focus on the main point: create a TextField subclass to include the autocomplete feature on it.

1. Add a new class to the project using Insert > Class. Type ‘TextFieldAutocomplete’ as the Class name in the Inspector, and type ‘TextField’ as its ‘Super’ class.
2. Add a new property (Insert > Property). Type ‘Autocomplete’ as the property Name, ‘Boolean’ as the Type, and ‘True’ for the Default field. Finally, select the ‘Public’ option for the scope. This property will let us to use the objects from the class as regular TextField, without autocompletion, or with the Autocomplete functionality.
3. Add another property, typing ‘AutocompleteSource’ for the property Name, setting the scope to ‘Public’ and its type to ‘TextAutocompleteSource’. That is the Data Type we have created as a Class Interface. This allows us to use any object that conforms to TextAutocompleteSource as the source for the Autocompletion Dictionary.
4. Let’s add a third property. In this case, use ‘TabKeyAutcompletes’ as the property name, ‘Boolean’ for the Type, set the Scope to Public, and its default value to ‘True’. We will use this property to set the behaviour of the Tab key between autocomplete the suggested word, or change to its regular behaviour when used on a TextField control.

Shared Properties

All the properties created for the subclass are Instance Properties. That is, every new instance (object) from this class will have its own set of values for these properties. In some cases, however, we want to share the value of one or several properties for all the class instances…and this is what we can achieve using the Shared Properties.

We will use two of these shared properties for our TextFieldAutocomplete class to see them in action. One of these will let us use the Suggestions Dictionary globally for all the class instances, always the property is not set to Nil. The second one will be an Array of Strings that will contain all the characters that we want to exclude from the typed on the textfield.

1. Add a new Shared Property to the Class, typing ‘globalAutocompleteSource’ for the Name field, setting the Scope to ‘Public’ and typing ‘TextAutocompleteSource’ as the Data Type for the Property.
2. Add the second Shared Property typing ‘SpecialCharacters(-1)’ as its name, setting the Scope to ‘Protected’ and ‘String’ for the Data Type.

TextFieldAutocomplete: a Matter of Methods

The next step is to add a couple of method to our class: the public interface. With them, the user of the class can set the no allowed characters.

• Add a new method to the class typing ‘AddSpecialCharacters’ as the name, ‘Value() as String’ for the Parameters field, and setting the Scope to ‘Public’. Type this line of code in the associated Code Editor for the method:

SpecialCharacters = Value

• Add the second method, using ‘SpecialCharacter’ as the method name, ‘Value as String’ for the parameters field, ‘Boolean’ as returned Type and setting the Scope to ‘Protected’. Type this block of code for the method:

If SpecialCharacters.LastRowIndex > 0 Then
  For Each item As String In SpecialCharacters
    If item = Value then Return true
  Next
End If
Return False

Handling Events

Our TextFieldAutocomplete class needs to be aware of every key down, so we are going to add the handler triggered in response of this event.

• Make sure that the ‘TextFieldAutocomplete’ item is selected on the Navigator and select Insert > Event Handler. This action will show a new window with all the available Events for the class. Select the KeyDown event and confirm clicking on the ‘OK’ button.

• Select the just added KeyDown event and type the following block of code. This is the place where we put the main logic for the class!

If Autocomplete = False Then Return RaiseEvent KeyDown(Key)

If SpecialCharacter(key) = True Then Return False

If Asc(key) = 9 And TabKeyAutocompletes = True And Me.SelectionLength > 0 Then
  Me.SelectionStart = Me.value.Length
  Me.SelectionLength = 0
  Return True
End If

Var tempText As String = Me.Value.Left(Me.SelectionStart) + key

Var matchingText As String

If AutocompleteSource <> Nil Then

  matchingText = AutocompleteSource.Match(tempText)

Elseif GlobalAutocompleteSource <> Nil Then

  matchingText = GlobalAutocompleteSource.Match(tempText)
End If

If matchingText <> "" Then
  Me.Value = matchingText
  Var startOffset As Integer = tempText.Length
  Me.SelectionStart = startOffset
  Me.SelectionLength = matchingText.Length-startOffset
  Return True
End If

Return false

Adding Class Events

Our class uses the KeyDown event, and that means that it will not be available for the new controls added to the project that would be based on this class. The solution? The Xojo language allows us to define new events for our classes, and we will use that feature in order to “duplicate” the signature of the used event on the class.

Make sure it is selected the ‘TextFieldAutocomplete’ item in the Navigator and then select Insert > Event Definition. The last action will bring us to the Inspector. Type ‘KeyDown’ as the Event Name, ‘Key as String’ as the Parameter, and ‘Boolean’ as Returned Type.

As you can see in the block of code of the previous section, we will call our defined event using the statement ‘RaiseEvent’, passing as parameter the same ‘Key’ String received in the original event.

Design the User Interface

Everything is now ready to test our Autocomplete TextField with Xojo! The first step is to choose the Window1 item in the Navigator, using the available UI Controls in the Library in order to design the interface as shown in this screenshot:

In fact, you have to use two CheckBox controls, one PushButton and one TextFieldAutocomplete, dragging the last one from the Navigator over the Window1 Layout Editor.

Double click the ‘CheckBox1’ labeled as ‘Autocomplete’ and add a new Event Handler. Choose ‘Action’ and click on ‘Ok’ to confirm the selection. Type the following line of code in the resulting Code Editor for the added ‘Action’ Event Handler:

TextField1.Autocomplete = me.Value

Repeat the same operation on the “CheckBox2”. In this case, type the following line of code on the ‘Action’ Event Handler:

TextField1.TabKeyAutocompletes = me.Value

Lastly, add the ‘Action’ Event Handler on the ‘PushButton1’ control, typing the following line of code:

Stack.AddWordToDictionary TextField1.Text

Start Your Engines!

Now we need to define the ‘Stack’ and the code responsible of putting our demo to work.

Make sure that the ‘Window1’ item is selected in the Navigator and add a new Property using ‘Stack’ as its name, set the Scope to ‘Public’ and the Type to ‘StringStack’. That is the base class previously defined and that conforms to the TextAutocompleteSource protocol.

Now, add the ‘Open’ Event Handler to ‘Window1’ and type the following block of code:

Stack = New StringStack(Array("object", "objection", "objective", "objector", _
  "desert", "deserve", "descend", "destroyer", "destruction", _
  "trail", "train", "trainer", "cup", "cure", "curiosity"))

TextField1.AddSpecialCharacters(array(chr(8)))
TextField1.AutocompleteSource = Stack

As you can see, when we instantiate a new object from the StringStack class, we use the Constructor to pass the Array of Strings. This way we have a simple dictionary whose contents allow us to test the Autocomplete TextField. Obviously, we can change the Dictionary used to any other object that conforms to the ‘TextAutocompleteSource’ protocol… even if it is a database!

Run the project and start to type on the Autocomplete TextField. If you start typing the characters of any of the words in the “Dictionary”, you’ll see the TextField will show a suggestion for Autocompletion. Press the ‘Tab’ key… and done!

You can download the Example Project used in this tutorial from this link.

You can watch the video (in Spanish only) that talks you though this example.

*Read this post in Spanish

It won’t be an RSS Reader with all the bells and whistles – 33 lines of code does have its limits. But you will learn how useful some of the available Xojo classes are, and you can use the code as the starting point for your own more dazzling RSS Reader. Ready? Start your engines with the Xojo IDE!

URLConnection, the class to talk HTTP

Undoubtedly, URLConnection is the main class we are going to use in this tutorial. In fact, we will create our own subclass based on URLConnection, so we can write the specialized behaviour that we expect from an RSS feed parser.

But before that, and as you can read in the documentation available about the URLConnection, this class allows us to receive and send information using the HTTP protocol. So, using a new instance (object) from our class we will be able to get the XML data associated with an RSS feed. For that we just have to make the request against the remote Web Server using the “Get” method from our URLConnection sublcass.

For instance, we can get the data associated with an RSS feed using the standard URLConnection class this way:

Var http as new URLConnection
Var feedXML As String = http.Send("GET,"http://blog.xojo.com/feed/")

As you can see, the “Send” method expects two mandatory parameters. The first one is the “Method” —Get in this case—, and the second is the source URL we are going to use to get the response (the data). The third parameter is optional and it allows us to set the timeout period associated with the request (defaults to 60 seconds).

Whether we use the timeout parameter or not, we would be using this method in a asynchronous way. That is, the code execution flow will continue is way while the connections retrieve the requested data.

The RSSReader Class

Now is time to write the subclass that will do the main work: get the XML data associated with the RSS source, and parse the nodes to retrieve just the information we want to use. For instance, in this tutorial we are interested only on the “Title” and the associated URL, so when the user selects any of the available items, we can show the full article on an HTML Viewer.

1. Add a new Class to the project using Insert > Class, and write “RSSReader” as the Class “Name” on the associated Inspector.
2. Add “URLConnection” on the “Super” field of the Inspector. This is the way we have to identify our class as a subclass of the standard URLConnection, thus inheriting its exposed methods, events and properties.
3. Add a Property, using “items(-1)” for the “Name” field of the associated Inspector, and “Pair” for the “Type” field. This will be Array in charge of storing all the retrieved items from the RSS feed.
4. Add a new Method named “GetFeed”, typing “url As String” on the “Parameters” field of the associated Inspector. Write this line of code in the Code Editor for the method (we could have opted for using a Computed Property or assigning directly the property with a Public scope, at your choice!):

If url <> "" Then Me.Send("Get",url)

ContentReceived, here comes the data

Let’s write the code in charge of parsing the received data from the requested URL! For that, we need to add the ContentReceived Event to our Class.

Make sure to select the RSSReader item in the Project Navigator and choose the Insert > Event Definition option from the menu. On the resulting window, select the ContentReceived item and confirm pushing the “OK” button. As result, Xojo will add the selected event to our class, with the Code Editor avilable and ready so you can write the following code:

If httpStatus = 200 Then
  content = DefineEncoding(content, encodings.UTF8)
  parseNodes(content)
  RaiseEvent refresh(items)
end

After we define the text encoding for the received content (UTF8), the following line calls the “parseNodes” method (not created yet). This method is the one responsible of parsing the received data. Once this has been done, the next line of code will raise the “refresh” event on the class instance, passing along the already parsed data.

Define your own Event: communication with the instance

Raising an Event is the way our class has to communicate with the instance you’ll add to the project, so it can interact with other UI components or methods, for example. For that, and with the RSSReader item still selected in the Project Navigator, select the Add to “RSSReader” > Event Definition option. Type “Refresh” in the Event Name field, and “items() as Pair” in the Parameters field. That’s all, you’ve created your own Event Handler for the subclass!

XMLDocument and XPath

Time to add the “parseNodes” method to the RSSReader Class, typing “content as String” as Parameter on the associated Inspector. Don’t forget to define the Scope of this method as Private, so it can’t be called from outside the class. Then, write the following code for the just created method:

Try
  Var xml As New XmlDocument(content)
  If xml <> Nil Then 
    Var nodes As XmlNodeList = xml.Xql("//item")
    Var title, url As String
    For n As Integer = 0 To nodes.Length - 1
      title = nodes.item(n).Xql("title").Item(0).FirstChild.Value
      url = nodes.item(n).Xql("link").Item(0).FirstChild.Value
      items.Append( New pair( title, url ) )
    next
  End If
Catch e As XmlException
  MessageBox e.Reason
End Try

The XMLDocument class available in the Xojo Framework allows us to easily edit and travel the XML structure, as is the case of the RSS feeds! In addition, we can use XPath (1.0) to make the queries on the XML structure. As you can see, I used the “//item” expression combined with the Xql method to get a list with all the nodes of interest from the XML document.

Once we have the nodes, we just need to use the For… Next loop in order to retrieve the “fields” that we are interested on from each available node. For that, we are going to use the Xql method too. Finally, we just need to create a new Pair with that information and store it on the Items property.

The User Interface

We have finished all the “hard work”, so now is time to create the user interface for our RSS Reader!

Choose the Window1 control in the Navigator to access its Layout Window. Then, add a new ListBox and HTMLViewer from the Library and arrange these controls as shown by the following image:

As you can see in the bottom of the Layout Editor, we added a RSSReader instance to the Window1 tray. For that, you only need to drag the RSSReader item from the Navigator and drop it in that area of the Layout Editor.

Adding the Refresh Event Handler to our instance!

We are mostly done! With the just added RSSReader1 instance to our project, select it in the Project Navigator and use the contextual menu to choose the Add to “RSSReader1” > Event Handler option. In the resulting dialog, select the “Refresh” Event Handler and click on the “OK” button in order to get it added to the instance.

Write the following code snippet for the added “Refresh” method:

Listbox2.RemoveAllRows

For Each item As pair In items
  Listbox2.AddRow item.Left.StringValue
  listbox2.RowTagAt(Listbox2.LastAddedRowIndex) = item.Right.StringValue  
Next

Showing a Webpage on the HTMLViewer

Choose the Listbox1 control on the Project Browser an add the Change Event. The only line of code you have to write is the responsible to load the webpage associated with the item choosen by the user on the ListBox:

If Me.SelectedRowIndex <> -1 Then HTMLViewer1.LoadURL me.RowTagAt(me.SelectedRowIndex)

Start engines!

In order to finish the tutorial, we just need to add a line of code to the Open Event to the Window1:

RSSReader1.GetFeed("https://blog.xojo.com/feed" )

As you can see, it was really easy and works seamless on macOS, Windows and Linux!

You can download the Xojo Project from this link.

You can watch the video (in Spanish only) that talks you though this example.

*Read this post in Spanish

But as these users advance in their Xojo skills, they probably will care about coding better and to embrace the OOP way of doing things. After all, Xojo is a modern programming language with Classes, Inheritance, Interfaces and a bunch of the usual OOP paradigms that have much to offer: reusability, better maintainability and a lot of flexibility.

When we talk about OOP, Design Patterns arise! Design Patterns are like  recipes, well known solutions or best practices, to a series of problems or situations that emerge again and again in our OOP designs.

These Design Patterns are so common that you are probably already using some without knowing it. And if you are curious about what are the most common and the code design problems they solve, then you have to definetly take a look into the BOOK (yes, in uppercase): “Design Patterns: Elements of Reusable Object-Oriented Software”

In this post I am going to focus on one of these particular Design Patterns and how to implement it in Xojo: Singleton.

OOP is mainly about the instantiation —or object creation— from a Class definition that acts like a template; so we can have several of these objects around sharing the same behaviour but with a state of their own. Well, the Singleton pattern is the “opposite” thing. The answer to having (generally) just one object around from a particular Class.

Why should we want this? The short answer: to limit the access or “enty point” to a main functionality of your apps, or when the created object has a high cost or high impact in used resources.

Implementing the Singleton Pattern

The key to implement this Design Pattern in your apps is to limit the instantiation of the Class to just one object. So let’s see how can we achieve this using the Xojo language features. These are the ingredients to the recipe!

A Class Constructor whose scope is set to Private. This is the way we will ensure that the Class consumer will not be able to create several instances using the usual syntax:

Dim myInstance as MyClass = new MyClass
Dim myInstance as new Myclass

A Shared Method (also known as Static Method or Class Method in other programming languages). This will be the entry point we will use in order to retrieve the unique instance allowed by the Class.

A Shared Property whose scope is set to Private. This one will be the responsible to hold (point to) the unique instance from… the same Class!

Now that we know what the ingredients are, let’s create our own “Hello Machine” as a Singleton Class. Obviously this is not the most useful class in the world, but maintaining the functionality to a minimum will help to focus on the main point about how to implement this Design Pattern in Xojo.

The “Hello Machine” Singleton

Start the new project creating a new Class using Insert > Class. Then, go to the Inspector panel and name the Class as “HelloMachine”.

With the new Class item selected in the Project Browser panel (the leftmost), add a new property to it using Insert > Property. Name the new property as “Counter”, set the Type as Integer and the “Default Value” to 1. This is the property that will inform us about how many times has been invoked the class.

Add a new method to the HelloMachine Class (Insert > Method). This will be in charge of providing the real functionality to our Singleton class. Use “Greet” for the method name and set the Scope to Public. Now, type the following code for the just created method:

MsgBox "Hello World! Is not funny being the only one instance on Earth?" + endofline + endofline + "You have invoked me " + counter.totext + " times."
counter = counter + 1

Now it is time to create the class members that will make our HelloMachine behave as a Singleton one.

Start adding the Shared Property that will be in charge to hold the unique class instance used by the App. Use Insert > Shared Property for that. Select the just added shared property and using the Inspector panel type “sharedInstance” for the “Name”, and set the type to “HelloMachine”; that is, the same Class type we are just defining (it sounds kind of weird, I know).

Now is time to add our Class Constructor. Remember that this one is the special Method whose code is executed every time we want to create a new instance (object) from a particular class.

Use Insert > Method and type “Constructor” on the “Method Name” field of the associated Inspector panel (or choose “Constructor” from the dropdown menu). Make sure you set the Scope of the Constructor method as Private. This way we will be sure that nobody will be able to directly instantiate new objects from the class.

Finally we will write the method that will act as the entry point to retrieve the unique instance available from the class; that is, the instance shared among the App.

Use Insert > Shared Method and type “getInstance” for the “Method Name” field. Make sure to set the “Return Type” field to “HelloMachine”.

Select the “getInstance” shared method and type the following code on the associated Code Editor:

If sharedInstance is Nil then sharedInstance = new HelloMachine
Return sharedInstance

As you can see, all the “magic” consists to verify if has been created already a HelloMachine instance (holded by the sharedInstance Property), returning it if is the case or instantiating and returning it, if otherwise. Voilá, a Singleton Class!

Singleton At Work

Once we have finished our Singleton class definition, let’s use it in our App. Add the Open event to the default window, for example, and type the following code in the Code Editor:

Dim myHelloMachine as HelloMachine = HelloMachine.getInstance
myHelloMachine.Greet
Dim myOtherHelloMachine as HelloMachine = HelloMachine.getInstance
myOtherHelloMachine.Greet

As you can see, we are not instantiating new objects from the Class, just using the Public method to retrieve the unique instance managed by the own Class.

Just for fun, try to instantiate a new object from the class using the regular syntax (I mean, with “Dim myHellowMachine as new HelloMachine”) and you will get a Compiler error. That is, no way to have several objects around!

Download an example using the Singleton Design Patter from this link.

You can watch the video (in Spanish only) that talks you though this example.

Javier Rodríguez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has used Xojo since 1998. He is in charge of AprendeXojo.com and the developer behind the GuancheMOS plug-in for Xojo Developers and the Snippery app, among others.

More Posts From Javier:

*Read this post in Spanish

As developers, the computed properties definitions don’t differ a lot from regular ones. For example, every time we create one of these properties via Insert > Computed Property, we will define the property name, type and scope as we would do in the case of a regular property; and when we refer to these kind of properties from our code, we will use the usual dot notation and, at the same time, we will assign new values using the habitual equal symbol (“=”).

As you can see in the screenshot, below the property name we find both methods: Get and Set. ‘Get’ is automatically invoked (and showed by the Debugger) every time we write for instance:

Dim textVar As String = myProperty

While ‘Set’  is the one automatically invoked every time we want to assign a new value to the property, using, for instance, a sentence like:

miPropiedad = MyTextField.text

But if you try to execute these examples just as they are, you will get errors from the Compiler. The property itself doesn’t exists yet, just this wireframe or umbrella! When we create a new Computed Property this way, we are creating the wrapper but still have to define the real container (the property itself) in charge to store the values processed by Set and Get. This is something we can fix very easily; just a matter of adding a new property and defining its scope as private. This way we will be sure that no other object can directly access the property. The only way to get and/or set its value would be from the Computed Property methods previously created.

In fact, the way you can more clearly see the relationship between a regular property and the Calculated Property wrapper is by defining the regular property in first place. Add a new property, select it from the Project Browser, access the contextual menu and select the ‘Convert to Computed Property‘ option, as showed in the following screenshot:

As result, you’ll find that Xojo’s IDE has included the wrapper previously seen, modifying the original property’s name to include the “m” character as prefix. At the same time, the scope will change to Private too.

The magic behind Set and Get

Behind of the sugar syntax they provide, the real power found in Computed Properties, when compared with regular ones, resides in the code that we can write on both, and that will be executed just before we retrieve the property value or just before we make a new assignation to it.

Following with our example, if we would be using the property to store a person name, we could use Set on such property to provide a default value if the received one is an empty string:

Set (Value As String)

If Value = "" then mMyProperty = "New User"

On the other hand, we could use the Get on the property to retrieve the associated value using a predefined format. In our example, this could be getting the name using TitleCase (I know, I know… we can do this from the Set too, but just wanted to illustrate the topic exposed).

Get As String

Return mMyProperty.Titlecase

Method Overloading

Did you know Computed Properties always were feasible in Xojo? I mean, what we find behind the Computed Properties on Xojo’s IDE is a help to us as developers in order to simplify the process (and from an organizational point of view of our code).

The truth is that we always could achieve the same results (and still is possible) using the feature available in every Object Oriented Programming language, as is the case of Xojo! I’m referring to Method Overloading. This doesn’t mean that you have to choose between using Computed Properties or Method Overloading… the point here is to introduce what Method Overloading.

Method Overloading is the ability we have to define multiple methods using the same name, as long as their parameters types and/or number varies, and/or the type returned from the method itself. So, it’s time to see how we can achieve the same results of a Computed Property using Method Overloading.

Start adding a new property via Insert > Property. Define its type (String in this example) and its scope as Private. Make sure to add the “m” character at the beginning of the property name! (in fact you can use any other character, but we use the “m” as convention).

Now it’s time to create our Setter method. For that, use Insert > Method on the same project item where you created the property. Use the same name of the property without the initial “m” as the Method name, and write the following code in the Parameters field on the Method’s Inspector Panel:

Assigns Value as String

Leave empty the Return Type field (type returned by the method) and select Public as the Method Scope.

The ‘Assigns‘ keyword provides the syntax sugar to use the equal symbol (“=”) on the parameter pass to the method. This way, we can invoke our method (myProperty on the example) as follows:

myProperty = "New Value"

Does it seems like we are not calling a method but making an assignation to a Property?

Let’s create the method in charge of the Getter and, for that, we will repeat the same steps involved in the creation of a new method. When done, using the same name, you’ll see that the Project Browser will group together both methods. In this case, as we want to define the Getter, we don’t need to define the parameters, just the returned type (String for this example).

This is the way it will look in the Project Browser:

As we have previously seen, the method overloading is possible because they differ in the provided parameters and/or returned type, despite they use the same name. That way, the Compiler will know exactly which one has to execute on runtime based on such information.

Done! You’ve learned what Computed Properties are and how they work from the OOP side of the Xojo’s language.

Finally, probably you want to know too that:

* Computed Properties appear in the debugger and cannot be overloaded on subclassses
* Getter/Setter method overloading does not appear in the debugger, but can be overloaded on subclasses and specified in interfaces.

You can watch the video (in Spanish only) that talks you though this example.

Javier Rodríguez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has used Xojo since 1998. He is in charge of AprendeXojo.com and the developer behind the GuancheMOS plug-in for Xojo Developers and the Snippery app, among others.

More Posts From Javier:

*Read this post in Spanish

Implementing this kind of behavior in your OS X apps is not rocket science! Follow these simple steps in order to register a custom URI from your app.

Register the custom URI you want to manage

You’ll need to modify the “info.plist” file generated by Xojo every time the app is compiled, so it necessarily involves the use of the powerful Build Steps! To smooth the road, follow these steps first:

1. Control + Click the OS X item under the Build Settings section of the Project Browser panel (the leftmost column in the Xojo IDE)
2. Select the option Add to “Build Settings” > Build Step > Script.
3. Paste the following code (make sure PlistBuddy from Apple’s Developer Tools is installed on your Mac!):

Dim App As String = CurrentBuildLocation + "/" + CurrentBuildAppName
call DoShellCommand("/usr/libexec/PlistBuddy -c ""add :CFBundleURLTypes array"" " + App + "/Contents/Info.plist" )
call DoShellCommand("/usr/libexec/PlistBuddy -c ""add :CFBundleURLTypes:0 dict"" " + App + "/Contents/Info.plist" )
call DoShellCommand("/usr/libexec/PlistBuddy -c ""add :CFBundleURLTypes:0:CFBundleURLName string 'Demo'"" " + App + "/Contents/Info.plist" )
call DoShellCommand("/usr/libexec/PlistBuddy -c ""add :CFBundleURLTypes:0:CFBundleURLSchemes array"" " + App + "/Contents/Info.plist" )
call DoShellCommand("/usr/libexec/PlistBuddy -c ""add :CFBundleURLTypes:0:CFBundleURLSchemes:0 string 'demo'"" " + App + "/Contents/Info.plist" )

Observe the use of the strings ‘Demo’ and ‘demo’ for the CFBundleURLName and CFBundleURLSchemes keys, respectively. The second one, CFBundleURLSchemes, is the customized URI that anyone will be able to use to pass information to our application.

Make sure to select the option “Both” on the Inspector for this build step, and type a name to identify this script  (for example, “Insert URI on Plist”). This way the URI will be registered every time you run the app from the Debugger or once it is compiled for deployment (release or standalone app).

Let your app react to the URI

The second main step is letting your Xojo app react to the URI, this is something you can do by adding the HandleAppleEvent event to the App Object.

As for the code, you will probably want to to use inside this Event, the main point is to identify the received Event and compare it to the “GURL” string, because this is the identifier used by OS X for sending an URI event:

    if eventClass = "GURL" then
      //do your thing
      return true
    end if
    return false

This way the app doesn’t interferes with the events we are not interested in.

It is very important to point out that the HandleAppleEvent event should exit with Return False for the ignored Events. Otherwise the user of your app probably will experience malfunctions using keyboard shortcuts on TextFields or TextAreas among other problems.

Getting the information

The final step is to extract the passed information along the “GURL” event. Xojo provides several methods that helps you do this; but for this example we are going to provide the code for the most common uses: getting the information sent as a text String.

    dim s() as string = DecodeURLComponent(theEvent.StringParam("----")).DefineEncoding(encodings.UTF8).Split(":")
    s.Remove(0)

The main point here is the ‘theEvent.StringParam(“—-“)’ code. This gets the string available and that is associated with the keyDirectObject key of the Dictionary (the value of that constant is the “—-” string used here.)

The second thing to highlight is that you have to assign a Text Encoding for the received string and use the DecodeURLComponent function to restore the original text sent along the URI (“demo:”, for this example).

Lastly, you can use the Split function to get an Array of strings so you can discard the first component from the received string (the URI itself) and join the remaining elements to get the final string.

You can watch the video (in Spanish only) that talks you though this example.

Visit this post to learn how to Customize URI Schemes on Windows.

Javier Rodríguez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has used Xojo since 1998. He is in charge of AprendeXojo.com and the developer behind the GuancheMOS plug-in for Xojo Developers and the Snippery app among others.

*Read this post in Spanish.

However, sometimes the combination can simply reach unstable situations by the very nature of our applications and here is where failures can arise in memory management. Fortunately, we can keep this under control with the help of the WeakRef class.

This is, in fact, what happened to me recently while implementing a new feature in Snippery my productivity application where one of those unlikely but possible cases one of the objects left in an unstable state. What does this mean? The referenced Control object stored in a property was not marked as nil once it was out of scope because its containing window was closed, so it was simply unsafe (an dangerous!) to check or access its properties and methods through a simple verification of the type:

if miPropiedad <> nil then

Despite the object referenced through the property would have been released, this condition will execute the code inside the block resulting in a unexpectedly exit from the app! In fact inspecting the object via Xojo’s debugger shows that the reference is still there but it inner structure is void.

So executing the previous code will bring a beautiful error message from OS X:

EXC_BAD_ACCESS (SIGSEGV)

That is an attempt to access a memory vector where we expected to find a data structure that is not there anymore.

I have to say that after further research on the subject I have found that this kind of error does not always occur and that it may depend on the type of object that we maintain the reference to, or even the property we want to access, or the method we try to call when the objects is in this “unstable” state. In the best of the cases, simply nothing happens. In the worst case, your application will suffer an unexpected exit you will not be able to trap using the Try … Catch block or exception handling mechanism offered by the Xojo language.

If you want to see for yourself what I’m talking about, you can download the example application that reproduces this kind of problem related with memory management.

WeakRef to the rescue!

How can we solve these kinds of situations? Easy! The WeakRef class allows code to maintain weak references to objects. When you wrap the object you’re interested in an instance of the class WeakRef, we will ensure that such reference is released (and thus becomes nil) through proper memory management. So, problem solved! From this point on we can perform and trust a conditional test of the reference against ‘nil’ before trying to access any of the properties of the object itself.

In the case of our sample application, we can fix the problem with the following changes:

1. We define the property SourceControl Worker class to be of the WeakRef Data Type
2. We make the following changes to Worker class constructor (where the referenced Control instance is now wrapped into a WeakRef instance):

sourceControl = new weakref( c )

3. We modify the conditional block of code for the Worker method to:

if sourceControl.Value <> nil then
  textArea(sourceControl).SelLength = 0
  textArea(sourceControl).Text = “This is a test”
end if

Note that in this case we Cast SourceControl to TextArea, so  we can work with the properties and methods of the control that we know are actually a control of TextArea type.

Make the changes, run the app again and you’ll notice that this time the app will continue running without errors once all the windows are closed.

You can watch the video (in Spanish only) that talks you though this example.

Javier Rodríguez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has used Xojo since 1998. He is in charge of AprendeXojo.com and the developer behind the GuancheMOS plug-in for Xojo Developers and the Snippery app among others.

*Read this post in Spanish.