We have cleaned up the maemomm API reference and put the result online. Here’s an example for the Hildon::TouchSelector widget. Pages such as that are linked often from the “Programming with maemomm” book.

Like the gtkmm API reference, the maemomm API reference is partly autogenerated from the C API reference, with some clever automatic changes, and some manual overrides, so it will improve as the hildon C API reference documentation improves.

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

I think the new Maemo 5 Hildon API leans too much towards extra API. For instance:

• 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.
• You must use HildonWizardDialog instead of GtkAssistant. This dates from before GtkAssistant existed, but the Hildon developers seem to have forgotten to deprecate it and adapt GtkAssistant for Maemo 5.
• You must use HildonFileChooserDialog instead of GtkFileChooserDialog or the other GtkFileChooserWidgets. These hildon-fm widgets have almost no documentation, so there’s no obvious reason for their existence.

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.

David King blogged that we have draft documentation online for the Maemomm (C++) API for Maemo 5.

The text needs to be filled out a little and corrected here and there. But we have figured out how to actually use the new widgets, as shown by our example code. And the list of screenshots of the examples is probably the first time you’ll see most of the new Hildon widgets all together. It’s radically different to the previous Maemo UI, rightly so.

I’m working on some example code for Maemo 5 as standalone modules with full autotools files.

I now have Desktop Widget example code working in the Maemo 5 Beta SDK, showing a simple clock face, using the drawing code from Davyd Madeley’s cairo-based custom widget example, with his kind permission. Implementing a Desktop Widget is much like implementing a regular GTK+ Widget: You can draw in the expose-event handler, or add child GTK+ (or Hildon) widgets.

I’ve filed documentation bugs to make it easier for the next person to figure out how to implement and install Desktop Widgets, and a few bugs about the Hildon documentation in general.

I expect the final Maemo 5 version to have many standard Desktop Widgets, far more attractive than this:

In Desktop Edit mode, you can move the Desktop Widgets around by dragging them with your finger, remove them by touching the X icon, or configure them by touching the spanner icon. You can add extra widgets (if installed) by touching the “Desktop menu”. Note that you need to apt-get update and upgrade after installing the Beta SDK to see the X and spanner icons.

The rendering artifacts (such as the white line at the top) are just a known bug in Xephyr (on the PC). They won’t appear when running on an actual device.