If you work with Canvas objects that need text handling in Real Studio/Xojo Cocoa builds you quickly realize that it works vastly different than in Carbon builds. This is because Carbon apps (through Apple Text Services) gives you a bunch of information for free. In Cocoa only text controls get that information and that presents some issues to Xojo developers creating custom controls that do keyboard handling.
The Formatted Text Control is a word processor control for Xojo that is based on a canvas subclass and it works in Cocoa – somewhat. If you try to do any international characters such as é or ü you quickly discover it doesn’t work like it should. This problem is not unique to just the FTC because the Xojo Code Editor is also based on a Canvas subclass.
Xojo released an open source plugin on Friday for those who want to create custom text controls with international support (and integration with some Cocoa features). The plugin is available on GitHub for anyone to use. That page is at https://github.com/xojo/TextInputCanvas and the direct download for the plugin is at https://942ca60ce8039dc2659a-a2bc01947b765e9363feed443ae584ec.ssl.cf2.rackcdn.com/b1a9e16622/TextInputCanvas.xojo_plugin (this may change soon).
We’ve been fortunate to work with Xojo Inc in getting the Text Input Canvas plugin for early testing and integration. This plugin works on Mac, Windows, and Linux and adds a number of events to the canvas control that you have to implement to get it to work. Among one of the more important events you now need to handle is the DoCommand event. The OS passes in all of the keyboard events the could happen including arrow key movement, delete and backspace keys, and insert new line to name just a few of the possibilities. If it’s actual text to be inserted (rather than cursor handling or selection changes) the InsertText event passes in the text as well as the range of the text. Incomplete text (such as the é and ü) that requires multiple steps in Cocoa get inserted using the SetIncompleteText event.
The control itself then wants to retrieve some data that Cocoa needs by way of several events such as the IncompleteTextRange and SelectedRange events. This allows the FTC to not only support international text in Cocoa but to also get use some OS level Cocoa goodies. Hover the cursor over a word and then press Control + Command + d to see the definition of the word just like any other Cocoa app.
Unfortunately, the current download for the plugin doesn’t have much in the way of documentation for how the new events work and what is required for it to function in Cocoa. This is unfortunate because it’s rather complex and we’ve spent a lot of time working with the plugin and with the Xojo engineers to get the FTC working properly (and we still have some things to work on). I guess this means that the best example/documentation currently available is the Formatted Text Control. Again, I expect this to change in the near future.
Today we are releasing FTC version 3.1 alpha 1 for Xojo. Since this requires the use of the Text Input Canvas plugin this is a Xojo-only solution. For those still on Real Studio you need to stick with version 3. Version 3.1 is a free upgrade to anyone that already owns version 3. All previous versions are eligible for a discounted upgrade. If you do not have an upgrade coupon from us, please send us an email at support at bkeeney dot com.
If you already are on version 3.0 you should have received email notifications from our File Share application.
UPDATE: I need to note that building for Carbon isn’t supported in FTC 3.1. The new plugin is Cocoa, Windows, and Linux compatible. If you’re building for Carbon you should continue to use version 3.0.