Documentation: How To Use Fremantle Widgets
 

Hello fellow Developers! Developers! Developers! :D

I just created a document outlining the use of some hildon widgets in Fremantle. Because the Hildon documentation and the HIG are still quite thin I personally had lots of problems getting the UI of Conboy done properly. After tons of emails and bug reports I think it´s only fair to share this information in a centralized document.

The idea was born by Jaffa here. And the document now contains everything that I can contribute to that subject. Only screenshots are missing, but I´ll add them tomorrow.

Please read it. And please comment or better directly change the document. I´m not a native English speaker, so if you are: Feel absolutely free to change spelling, grammer etc...

If you´re a developer and you have some experiences with Fremantle UI, then please share your knowledge here:
http://wiki.maemo.org/Using_Fremantle_Widgets

Enjoy!
Conny

Re: Documentation: How To Use Fremantle Widgets
 

Thanks conny, that made a very interesting read!

Re: Documentation: How To Use Fremantle Widgets
 

Good work Conny, not only on the documentation but also on your port of tomboy. Keep up the good work.

Re: Documentation: How To Use Fremantle Widgets
 

The screenshots are now added - so I'm done for now. Everyone else, please share what you've learned while writing Fremantle UI code!

Thanks!
Conny

Re: Documentation: How To Use Fremantle Widgets
 

Good stuff. From a themeing perspective, the most common mistakes I encounter are:

- Use HildonEntry instead of GtkEntry. This is a no-brainer, and HildonEntry completely replaces GtkEntry. The only caveat is that HildonEntry has to be at least 70px in height (and ideally exactly 70px). This is ensured when using the constructor with HILDON_SIZE_FINGER_HEIGHT flag, and will also be the default size for subclasses soon.

- Make sure buttons get the correct themeing hint. Most buttons should either be finger height, or thumb height, by using hildon constructor functions and the appropriate size flags. If this isn't possible then hildon_gtk_widget_set_theme_size() can be used instead, but it requires that the classname ends in *Button (because it sets the widget name to <ClassName>-size (e.g. HildonButton-finger) and the theme is matching widgets ending in *Button-finger). Otherwise the widget name has to be set manually. This also goes for HildonCheckButtons and other widgets which look like buttons.

If you absolutely have to use auto sized buttons, try not to mix them with properly themed buttons, or it will look very inconsistent.

- Any custom button that acts like a picker button (pressing it allows you to choose a value, which is then displayed in the secondary line of the button) should use the picker style, which can be set with hildon_button_set_style (button, HILDON_BUTTON_STYLE_PICKER).

- Avoid notebook tabs, in most cases it is better to split things up into multiple windows, or to use a pannable area with group titles.

- Speaking of group titles, this is still a bit of a work in progress. But the bottom line is that you should put every group in a GtkFrame, and add 35px of vertical spacing between the groups. This may look odd right now in the SDK, but that will be fixed.

- Avoid comboboxes at all cost! Try to find an alternate method using HildonEntries or picker buttons. We will have one supported method of creating a widget that looks liked a ComboBoxEntry (unified look of entry with a button/arrow on its right), but its implementation is a bit involved and not really intended for regular applications.

- Don't add custom borders and margins without a specific purpose. Elements like HildonButtons and HildonEntries generally already have themed margins and are meant to line up neatly when placed next to each other.

- Avoid labels. New UI elements are generally designed in a way that uses the whole space for the widget, instead of requiring extra space for the label. This is why HildonCheckButtons put the label and checkbox on a button, and HildonEntry has the placeholder text.

If you are at all unsure about something, I suggest to post your UI on this forum and ask for suggestions. I will do what I can to help out, and hopefully we will be able to create a development culture where people get excited about creating slick and consistent UIs down to the last pixel. :)

Re: Documentation: How To Use Fremantle Widgets
 

If you think that the API references for hildon-widgets are unclear or miss something important, please do file a bug report against "Desktop platform > hildon-widgets" with the "docs" keyword set, Version set to "5.0-beta", and the exact URL of the existing API reference set in the URL field in http://bugs.maemo.org .
If there are issues, let's make it easier for every developer by providing better documentation. And the libhildon/hildon-desktop/hildon-widgets hackers have been quite responsive so far IMO.

Re: Documentation: How To Use Fremantle Widgets
 

Yes they are very responsive, I even own them two replies myself :)
The problem is that the HIG is not continuously updated (last release was in April) and that we cannot see the Nokia build-in software yet. This leads to a situation were many people are unsure what the most correct/consistent way of doing things is.
I'm quite sure that as soon as the final HIG is out this article doesn't make any sense anymore. But for now I think it's useful and it's nice that people are contributing :) Of course if I find something particular I'll file a report, but Murray is already quite active in this area.

Re: Documentation: How To Use Fremantle Widgets
 

fyi, on Gtk+ widgets supported in Maemo 5: http://wiki.maemo.org/Talk:Using_Fremantle_Widgets

The plan is to make a first release of the Hildon UI spec within few weeks (comprising the information relevant to application developers) and publish the second and final release including all the specs relevant for platform developers later on by the launch of Maemo 5.

Re: Documentation: How To Use Fremantle Widgets
 

conny, that document is really great. Thanks so much for all that work!

Re: Documentation: How To Use Fremantle Widgets
 

Just added a small section about the the different widget sizes here: http://wiki.maemo.org/Using_Fremantl...s#Widget_Sizes