Hildon 2.0 Changes Overview

Rationale

The purpose of the 2.0 cleanup is to get rid of old, poorly designed API's and solutions. The idea is to bring the hildon components as close as possible to the original design and common API practices seen in the G-components (most notably Gtk). As a result some semantical and structural changes were introduced to hildon. Some of the modifications are trivial (ie. function naming unification), some require design changes as the behavior has been altered.

It's worth noting that some changes (including the most drastic ones) were announced earlier in the past - by marking components and API calls as deprecated. Those deprecated components were finally removed from the 2.0 version of the library.

When porting your application to hildon-1, you should start by running your code through the hildon-audit tool. This will give you detailed instructions about the changes needed. The following document is meant to serve as an overview of the bigger differences between old and new hlidon. Cosmetic changes reported by hildon-audit are not covered here.

Packaging and handling

• hildon-libs has been now renamed to hildon (hildon-1 to be precise, first version of the API)
• hildon-lgpl has been removed.

• Headers are now installed into $PREFIX/usr/include/hildon-1

• In your configure scripts you should check for the presence of hildon-1. Ie:

PKG_CHECK_MODULES(HILDON, [hildon-1])
AC_SUBST(HILDON_LIBS)
AC_SUBST(HILDON_CFLAGS)

• The pkg-config module name is now (obviously) hildon-1

• In your application you should include:

#include <hildon/hildon.h>

...

Hildon-1, just like gtk+-2.0, is guaranteed to be API-stable during the '1' series of the releases. Hildon-1 depends on Gtk 2.10 and cannot be used separately.

HildonWindow vs HildonAppView

This is the most intrusive change to the API and has been suggested in the past. It boils down to using HildonProgram and HildonWindow instead of the HildonApp and HildonAppView. Detailed description of the changes required can be found in a separate document https://stage.maemo.org/svn/maemo/projects/haf/doc/hildon-window-migration-guide/

See also Hildon/TwoPointZero/WindowAndProgram

Infoprints and banners

The gtk_infoprint_, gtk_confirmation_banner_ and gtk_banner_ collection of functions has been removed. It's replaced by the HildonBanner and the respective equivalents. HildonBanner comes in three basic flavors - information, animation and progress. The first one is timed by default - it automatically disappears after a certain period of time. The others need to be manually destroyed.

Note that the HildonBanner exposes now functions that accept printf-like formatted strings for more convenient usage.

Unused widgets

As a part of the consolidation effort the unused, historical widgets were removed completely. The functionality provided by those widgets was not really well thought and in many cases was overlapping with functionality exposed by other parts of the framework. At the moment of writing not a single application was found to be using the unused widgets:

• HildonAddHomeDialog

• HildonFileHandlingNote

• HildonTelephoneEditor

• HildonGrid

• Timers and timestamps

Additionally some functions of the existing widgets were dropped/replaced. The changes are described in hildon audit and in most cases require trivial search & replace. No functionality of the existing widgets was compromised.

Password dialogs

Hildon provides three types of password dialogs:

• HildonSetPasswordDialog - used to set new password to protect something

• HildonGetPasswordDialog - used to ask the user for a password to unlock something

• HildonLoginDialog (previously: HildonNamePasswordDialog) - used for a login/password protected area

All dialogs accept a _set_message function (ie. hildon_login_dialog_set_message) that can be used to display a user-visible message on the top of the dialog. Previously a 'domain' property was used for this purpose. The domain was supposed to represent the area you're setting/getting the password for. This was, however, found to be not flexible enough.

With the 'message' property you can achieve same result. You can ie. set message to 'Please enter password to access the encrypted data' or you can just set it to 'Please enter password'.

Historically password dialogs had some severe input-method related errors that forced users to implement their own password-retrieval dialogs. This approach should be abandoned as password dialogs are now fully functional.

Insensitive press

A common task in a Hildon application is to create banner spawned when the user clicks an insensitive widget. In the past this was usually done by connecting to the 'insensitive-press' signal and manually creating an informational hildon banner. This approach might still work currently, but will mostly likely break in future. Instead, one should use hildon_helper_set_insensitive_message or hildon_helper_set_insensitive_messagef to directly set a text to display when the user clicks a widget in a disabled state. when using those utility functions it's not needed to manually create the banner/callbacks.

It's recommended to do so since 'insensitive-press' signal can be replaced in future with generic gtk tooltips. The helper function will however always stay functional. You should never use the 'insensitive-press' signal directly.

Other utility functions

The Hildon helper section contains some other utility functions that are typically used in applications. In example, using hildon_button_event_is_finger you can probe if a given event is a finger event. Additionally all stand-alone rc-related (logical colors, logical fonts) functions were moved to the helper section.

Help routines

In hildon-libs it was possible to use low-level functions to enable/disable the help button on dialogs. Those functions are removed now and the only way of accessing all help functionality should be through libhildonhelp. The direct replacement is hildon_help_dialog_help_enable but it should be noted that this function is much less fine-grained. Fine-grained low-level implementation of help functionality in applications is discouraged.

Plugins and color selecting widgets

The plugin functionality introduced in late hildon-libs is now removed. Pluggable widgets support might come some time in far future but this has to be carefully planned at the Gtk-level. The existing plugin interface was limited and confusing from the GObject design point of view. It was removed not to encourage implementators to use it and rely on it.

The only single plugin (the color selector) ever wrote has been moved to static code. Overally, the following color widgets are available:

• HildonColorButton

• HildonColorChooserDialog

• HildonColorChooser

The existing color chooser is an HSV-plane implementation of the color chooser. It's embedded in the color chooser dialog. From the application point of view, the most interesting widget remains still the HildonColorButton - which handles the whole color-selecting process (spawning the dialog, fetching color, etc.) automatically.

Hildon Note

Historically HildonNote has been truncating the content to 5 lines of text. This has been found to be problematic as:

• Some translations do not fit five lines
• There is no reliable way to tell if the text will be truncated or not

• When passing any kind of dynamic data to HildonNote you can't be sure if the user will see the important part (ie. security information)

• HildonNote can display much more than 5 lines while still looking correct and not taking 100% of the screen estate

Therefore, HildonNote does not truncate the textual content anymore. Existing users of the [HildonNote] do not need to do anything - the note will work as it worked before. New users can benefit from the new HildonNote behavior by using it to display dynamic data.

Menus and toolbars

The menu and toolbar memory-management behavior in HildonWindow has been altered. In the past, toolbars added to the HildonWindows (using hildon_window_set_toolbar) were automatically destroyed when the HildonWindow was destroyed. Menus, however, attached to windows using hildon_window_set_menu were not automatically destroyed and the application writer was responsible to care about this himself. This inconsistency was error-prone and lead to memory-leaks.

The new behavior is that both toolbars and menus added to the window using hildon_window_set_ are owned by the window and should not be destroyed by the application. Manual invocations of the destroy functions should be removed from the old code.

Note that the behavior of setting common toolbar and common menu (hildon_program_set_common_) don't change.