Maemo: APIs and Porting

This post is a general ramble about the limits of keeping API the same on significantly different platforms. It uses Maemo’s Hildon and Maemo’s Qt as examples, but don’t get offended. Hildon’s new UI in Maemo 5 is wonderfully appropriate for small touch-screen devices, and the API is the best that the developers could do in the short time available, in their circumstances. Not much can be changed in Hildon now anyway until a theoretical Maemo 6. And Maemo’s Qt is only just getting started.

Hildon: Secret, Then Public, Then Secret, Then Public

The first version of Maemo’s Hildon API added lots of API to hildon itself, and to the Maemo version of GTK+. It also made some inappropriate changes to default behavior. These things happen when work is done in secret, because people can’t complain until too late. Much of this was corrected in Maemo Diablo, as changes were sent upstream to GTK+.

Then Nokia made Hildon’s development secret again and added lots of new API. That’s now public again. Some simple things should be patches to GTK+ that can eventually be accepted in upstream GTK+. For other things, it’s debatable whether we would want the change in functionality to be obvious in the code (via #ifdefs), or if the standard GTK+ widgets should just behave differently when the same code runs on Maemo. For various things, both opinions are valid. But that discussion never happened because the API was not published until it was too late to change it significantly.

Too Much Simple New API

You must use HildonButton, HildonEntry and HildonTextView instead of GtkButton, GtkEntry, and GtkTextView. These have extra features, but they could be added to the GTK+ widgets.

You must use HildonCheckButton instead of GtkCheckButton or GtkRadioButton, though that’s really just to get a slightly different appearance.

You must use HildonWindow instead of GtkWindow.

HildonNote and HildonBanner add timed behaviour and convenience API that could just be in GtkDialog.

HildonAppMenu is just a glorified grid container, needing significant changes to application code, instead of the regular GTK+ menu APIs being changed to behave differently on Maemo. Now you can’t use GtkMenu, GtkUIManager or Glade for menus. Menus really must be made simpler for Maemo applications, but that’s no reason to completely change the menu API.

You must use HildonTouchSelector (via a HildonPickerButton) instead of a GtkComboBox. Admittedly it would be particularly difficult to make GtkComboBox act like a (pannable) HildonTouchSelector, and GtkComboBox would need extra API to allow multiple-selection. But there would be great benefits for application coders from that hard work.

Note that extra API is not just annoying when porting (requiring ifdefs) but also makes existing generic GTK+ documentation and skills less relevant to Maemo. Just because a UI has a wonderful new look and feel, that doesn’t mean you need a lots of arbitray new API to make things feel new and different for the developer too.

Too Much Surprising New Behavior

Where Hildon _has_ changed the GTK+ implementation instead of adding new API, it’s done it for situations that are too complex or where the changed behavior is annoyingly arbitrary. This is particularly annoying because there are reasonable uses of the original widgets even in a Maemo application. For instance:

The GtkTreeView’s selection and activation behavior is apparently entirely different, though I admittedly don’t know all the details yet. It apparently feels like a different widget so it probably should be a different class. Column headers are off by default too.

GtkEntry (ignoring that you should use HildonEntry) still defaults to auto-capitalization. I don’t think this is the common case. Most text in entry widgets is not a sentence or a name.

In these cases, the developers have justified the annoying new defaults by saying that it’s what the Maemo UI guidelines demand, ignoring that those guidelines do not say how the UI should be achieved in terms of API. Simply telling application developers to call extra API when using Maemo would have the same results without the annoyance.

Will Qt Make Better Choices?

Qt has long touted the similarity of its API across three major desktop platforms (Linux, Windows, Macintosh), though the nativeness of the results is debatable. At least Windows applications have no consistency anyway.

The Maemo Qt developers insist that they will stick to this even when porting to Maemo – probably the first popular Qt platform with a significantly different UI and desktop environment, requiring new concepts that are not yet in the Qt API.

I think that’s a good idea, though I doubt that it will really be possible. When I asked (threaded view) them, I discovered that they really hadn’t thought much about it yet and weren’t able to address my specific examples with anything other than a repeat of the Qt “deploy without rewriting the source code” mantra. Surprisingly there are not that many people working on Maemo’s Qt and it’s obviously far from ready for Maemo 5’s new UI. Nokia acquired all the Trolltech/”Qt Software” developers but if they have been redirected to work on Maemo then it’s not happening in public.

Hopefully they will at least choose to lean more towards maintaining API compatibility while adding API only where absolutely necessary. I think it must be a little of both.

Post navigation

6 thoughts on “Maemo: APIs and Porting”

Thanks for the post :) The worst problem I see here is the fact that apps specifically written for Maemo 5 cannot just be compiled on a Linux Desktop, but have to be “ported” to the Linux Desktop (and vice versa). Using stock GTK+ with modifications and little extensions would allow application code exchange in both directions. Last time I checked (in the beta SDK), the Hildon libraries (build-)depended on closed code from Nokia, so it is at least a bit more difficult than just re-compiling apps written for Maemo 5 on, say, a stock Debian on your Desktop machine.

Their Qt on Maemo approach does not seem that different from GTK+, they just did not have enough time to diverge significantly. Even now though, code sometimes needs to be #ifdef-d because of Qt-on-Maemo peculiarites which were indented as developer aids, but manage to break existing features in the process (for example hardcoded QActions, disabling statusbar by default, input handling, etc).

Your concerns are understandable, and I’m sure that many other developers share them, so I think I’m going to write a post to try to explain some of the decisions taken when writing the new API for libhildon.

Note that some of the things that you mention were already there in previous versions of Maemo (HildonWindow, HildonFileChooserDialog, HildonWizardDialog, HildonBanner, HildonNote), so we can’t say much about them. Others are not hard requirements (e.g. you _can_ use GtkWindow instead of HildonWindow).

Others were caused by lack of time or control, others by changes during the project, and I’m sure that others were probably mistakes (fortunately some of these are being worked on).

Now that the beta SDK is out and the development is open we can get some more feedback from the community, and some comments and bug reports have been helpful for us to see the point of view from the outside.

Berto, thanks for your comments; and they follow on from our discussion on #maemo.

The problem is that the ones from previous versions of Maemo (HildonWindow et al) just show that the original “secret” development phase produced a sub-optimal API; and none of the API compatibility breaks took the opportunity to sort it out.

You say “you _can_ use GtkWindow instead of HildonWindow”, but anyone doing that has a broken looking application (certainly with pre-Maemo 5) – so it’s a false benefit.

Having a completely separate API is fine (works for iPhone, Symbian, Android etc.) but it requires a definitive reference manual and a good set of tutorials. Someone starting developing for Hildon has both Hildon and Gtk+ APIs available, with lots of Gtk+ tutorials and books available – some of which aren’t relevant for Maemo.

About the GtkWindow vs HildonWindow problem: I was not there when that widget was created so I cannot tell you all the reasons, but after my experience with Hildon in Fremantle my impression is that:

1) It’s difficult (and slow) to change things in Gtk (even in Maemo-Gtk). It’s not that they can break other apps in unexpected ways, it’s also that it’s difficult to maintain then and to move them upstream (the Maemo-Gtk maintainers can tell you better than me).

2) HildonWindow just added a couple of features that probably didn’t make sense in GtkWindow (toolbars and the menu). Apart from that, it’s a completely standard GtkWindow that can be used with exactly the same API. All Gtk documentations is still valid.

In general, I don’t think we added that many new widgets in Fremantle (many of the widgets that Murray says were already there in Diablo and before), and time constraints didn’t let us a minute to even think about what to do with the old API.

I admit that the case of HildonCheckButton is arguable, but in general we only added new widgets when there was no real equivalent in Gtk.

Also, I have the feeling that some of the judgments I’ve heard these days (including some in this post) are general impressions obtained after an overview of the new API. E.g. GtkButton *IS* definitely supported in Fremantle. HildonButton is a different widget which contains two separate labels (although I admit that the name may lead to confusion). The Hildon HIG explains that you can use a standard GtkButton if that’s what you need.

Finally: I think that Murray is wrong wrt GtkTreeView. In this case new features were added to GtkTreeView (in particular a new property to change the UI mode) but the old behavior was kept, and is configurable.

And well, I think I wrote enough for today :) As I said in an earlier comment, I’ll try to find the time to write a post about all these things in my blog.