Documentation/Maemo 5 Developer Guide/Architecture/UI Framework

=UI Framework= The Fremantle UI Framework consists of the Clutter OpenGL-based canvas library, OpenGL drivers for the PowerVR SGX chip, Matchbox Window Manager 1 (for startup sequence) and Matchbox Window Manager 2 library, Hildon Welcome (“Nokia hands”) screen, Startup Wizard, application framework startup scripts, game startup system, Hildon Control Panel, some Control Panel applets, Restore original settings & Clear user data framework, Hildon Input Methods, internationalisation i.e. so-called POSIX data, Clipboard Manager, Hildon Desktop, notiﬁcation service, Hildon Home (applet loader), Hildon Status Menu/Area (plugin loader), and Status Menu USB plugin.

hildon-desktop
The hildon-desktop process acts as a compositing window manager for all applications. All screen painting, including painting of X windows, is done through the Clutter canvas library and OpenGL ES v2.0 API. Compositing means that hildon-desktop tells the X server (through the X Composite extension) to draw all windows to an off-screen buffer, instead of drawing them directly to the framebuffer. This allows hildon-desktop to modify window contents before drawing them onto the screen.

In Fremantle, compositing is used to implement window transitions and blurring of the screen. hildon-desktop handles all mapped windows as Clutter actors, which are objects usually containing an OpenGL texture. As the window manager hildon-desktop will reparent application windows to decorate them with the application title bar and close button. Windows on the screen will normally be oriented in landscape, but the window manager will have a limited support for portrait mode, using the Xrandr extension.

Task launcher and Task switcher (aka. Dashboard, Task navigator) is implemented by the hildon-desktop process. Task launcher is a menu the user can access to start new applications or bring running applications on top. Task switcher is a view to switch between running applications, some of which might be ’background killed’, which means that they appear running to the user but really have saved their UI state and are started by hildon-desktop on demand. Task launcher and switcher UI transitions could be challenging to implement with traditional toolkits, but hildon-desktop can use Clutter and hildon-desktop’s internal data about application windows to give a good performance.



Low memory and background killing D-Bus signals
The hildon-desktop process will listen to D-Bus signals warning about low-memory (RAM) situation (preventing starting of new applications) and signals suggesting starting background killing of applications that are running in the background. These signals are broadcast on the system bus by the hulda daemon (of Data Management). Only the applications that have told hildon-desktop that they can be background killed are considered for background killing. The property is set with the hildon_program_set_can_hibernate function in the libhildon1 library. The background killing signals are defined as follows:

The low-memory signals are defined as follows. Notice that these low-memory signals are not meant to be used outside of the application framework, there are separate signals (user lowmem on and user lowmem off ) for applications.

D-Bus signal for closing applications
The hildon-desktop process will listen to the ’exit’ D-Bus signal. When it catches the signal, it sends the (POSIX) TERM signal to all running windowed applications. This is used by the Backup application before restoring backed up data and settings, Backup itself can ignore the TERM signal. The signal is not meant to be used outside of the application framework.

D-Bus signal for ‘application died’ information note
The hildon-desktop process will have a D-Bus service for showing the ’application died’ information note. The service is used by the maemo-launcher daemon, when an application started by maemo-launcher dies, it causes showing of the note by broadcasting the following signal.

D-Bus service for application launching
hildon-desktop implements a D-Bus interface for launching applications. Application can be started by sending the D-Bus message mentioned in Section 6.2.

D-Bus service for moving from fullscreen application to Task switcher
Fullscreen applications cannot be minimised with a hardware key because there is no key reserved for that, so hildon-desktop provides a D-Bus interface for requesting it. This can be done by sending the following D-Bus signal.

Shutdown signal
hildon-desktop catches the following D-Bus signal on the system bus.

Portrait mode API in window manager
The hildon-desktop process has a limited support for the portrait mode. The current thinking is that an application ﬂags a window with a special window property when the whole screen should be turned to the portrait mode. The application will use the accelerometer’s output and its internal state for the decision to set the ﬂag.

The ﬂag will only be a hint for the window manager, though, because there could be a dialog waiting for the user’s input open, and then the portrait mode will not be entered until the dialog is closed. The current plan is that most dialogs appearing in the portrait mode would cause transition back to the landscape mode before showing the dialog. The dialogs that support both modes would be ﬂagged for the window manager by the application. The Status area window is not sensitive to input in the portrait mode, and the Tasks button will not be visible there. Incoming event windows will be shown in both landscape and portrait modes. Text input methods will not be supported in the portrait mode, i.e. there is no on-screen keyboard in the portrait mode. The Xrandr extension is used to change the screen orientation.

Hardware keyboard key bindings
In Diablo, there is a set of keys under the Gconf path /apps/osso/keybindings to conﬁgure what hardware key (home, power, menu, fullscreen, etc.) shortcuts do in the desktop. In Fremantle, there are no key bindings for hildon-desktop.

Full screen mode
Applications can request to go in and out of the full screen mode by using the gtk window_fullscreen and gtk window unfullscreen functions. The WM will see the desired mode from a window property. See the Gtk+ documentation for more information.

hildon-home
The hildon-home process implements loading of Home applets, notiﬁcation service, and loading of Home background images. There are multiple Home views, and the user can select between them by horizontally scrolling the screen. Each of the views can have a different set of dynamically loaded Home applets, a small Gtk+ applications with their own, possibly transparent, X window displayed on top of the Home background. Home has a layout mode in which the applet windows can be moved, resized, and dragged to a neighbouring Home view.

hildon-desktop handles positioning and displaying of the Home applets and background pictures according to the currently selected Home view. hildon-desktop also implements the Home layout mode in cooperation with hildon-home. Home ﬂags the applet windows with speciﬁc window properties to tell hildon-desktop to handle them in a special way. Home also stores the applet positions and the Home view where they are active to GConf for hildon-desktop.

hildon-home provides a service on the D-Bus session bus to display notiﬁcations on the screen, based on a proposed freedesktop.org Desktop Notiﬁcation Speciﬁcation6. Typical notiﬁcations are incoming e-mails, chat messages, and missed phone calls. The service supports persistent notiﬁcations that are retained over a reboot, simple dialogs with return values, and queueing of notiﬁcations. It is also possible to install plugins for the notification service, e.g. to support sound and vibration effects in connection to notifications.



Notification D-Bus service
The hildon-home process provides the Desktop Notiﬁcation Speciﬁcation D-Bus API documented in specification. Notification can be specified to be persistent over device reboots by giving the ‘persistent’ hint in the D-Bus message. The org.freedesktop.Notiﬁcations interface recognises the following two additional messages for backwards compatibility.

System information banner
The following D-Bus message can be used to show a system information banner. This is used by the Libosso function osso system note infoprint. The ’standard’ Notiﬁcations API should be preferred over this for new applications.

The return value is of the type DBUS TYPE UINT32, it is the ID of the notiﬁcation.

System information note
The following D-Bus message can be used to show a system information note. This is used by the Libosso function osso system note dialog. The ‘standard’ Notiﬁcations API should be preferred over this for new applications.

The return value is of the type DBUS TYPE UINT32, it is the ID of the notiﬁcation. The dialog’s return value can be retrieved by listening to the NotiﬁcationClosed signal that bears the ID.

Notification plugin interface
The notiﬁcation service supports plugins for e.g. sound and vibration functionality. The plugin code is not allowed to block.

Home plugin Public API

 * Every Home applet inherits from HDHomePluginItem GObject class. HDHomePluginItem is a descendant of GtkWindow, so to add a widget to the Home applet, you should use the gtk_container_add function. *Visibility of the applet is handled by hildon-home.
 * The applets can have only tap interaction (because of panning of Home screens)
 * The applets cannot have focus (because of the "call from Home" feature)
 * Class methods:
 * const gchar *hd_home_plugin_item_get_dl_filename (HDHomePluginItem *item);
 * DBusConnection *hd_home_plugin_item_get_dbus_connection ( HDHomePluginItem *item, DBusBusType type, DBusError *error);
 * DBusGConnection *hd_home_plugin_item_get_dbus_g_connection ( HDHomePluginItem *item, DBusBusType type, GError **error);
 * guint hd_home_plugin_item_heartbeat_signal_add ( HDHomePluginItem *item, guint mintime, guint maxtime, GSourceFunc source_func, gpointer data, GDestroyNotify destroy);
 * void hd_home_plugin_item_set_settings (HDHomePluginItem *item, gboolean settings); /* Whether the applet supports settings */
 * gchar *hd_home_plugin_item_get_applet_id (HDHomePluginItem *item) 

Applet should install a desktop file, e.g.:

[Desktop Entry] Name=Example Home Applet Comment=Description of the Example Home Applet Type=default X-Path=example-home-applet.so     X-Multiple-Instances=true X-Text-Domain=gettextdomain X-Display-On-All-Views=no

To specify default position, Gconf schema should be installed. E.g.:

  /schemas/apps/osso/hildon-desktop/applets/calendar-home-applet.desktop/view /apps/osso/hildon-desktop/applets/calendar-home-applet.desktop/view int 1             /schemas/apps/osso/hildon-desktop/applets/calendar-home-applet.desktop/position /apps/osso/hildon-desktop/applets/calendar-home-applet.desktop/position list int [10,20]            

In contrast to Status Menu and Notification plugins Home applets are not enabled by default but need to be enabled in the home.plugins file (/etc/hildon-desktop/home.plugins or ~/.config/hildon-desktop/home.plugins).

API for creating Web bookmarks
The libhildondesktop library provides function hd_shortcuts_add_bookmark_shortcut for adding a Web bookmark shortcut on Home.

hildon-status-menu
The hildon-status-menu process implements Status menu and Status area. The Status menu displays windows of dynamically loaded Gtk+ applets. All available Status menu applets are displayed in the menu, and some of them might have an icon in the Status area, depending on the conﬁguration. Status menu applets can start new applications using the D-Bus autoactivation system, and they can display controls that the user can directly manipulate on their window. The Status area is basically a button that allows the user open the Status menu. Status area expands to accommodate its plugin icons (from selected Status menu plugins), but it has a pre-conﬁgured limit for the maximum number of plugin icons.

Status menu plugin API

 * Status Area and Status Menu plugins are the same: every Status Menu plugin can show up on Status Area, too.
 * Plugins inherit from HDStatusMenuItem (subclass of HDStatusPluginItem, which is subclass of GtkBin) GObject class, which has these class methods inherited from HDStatusPluginItem:
 * Function for setting (or changing) the Status Area icon (GdkPixbuf): hd_status_plugin_item_set_status_area_icon, ::status-area-icon property
 * Function for setting GtkWidget instead of GdkPixbuf as the Status Area icon: void hd_status_plugin_item_set_status_area_widget ( HDStatusPluginItem *item, GtkWidget*widget);
 * Function for registering callbacks using the system-wide synchronized timers: hd_status_plugin_item_heartbeat_signal_add
 * Function for getting name of the plugin file, e.g. get_dlfilename: hd_status_plugin_item_get_dl_filename, ::dl-filename property
 * DBusConnection *hd_status_plugin_item_get_dbus_connection ( HDStatusPluginItem *item, DBusBusType type, DBusError *error);
 * DBusGConnection *hd_status_plugin_item_get_dbus_g_connection ( HDStatusPluginItem *item, DBusBusType type, GError **error);
 * HD_DEFINE_PLUGIN_MODULE macro is used to define the plugin class as subclass of ''GTypeModule'.
 * Plugin widget's standard GObject constructor and destructor are used.
 * Widget's visibility (in Gtk) is used to show and hide the plugin.
 * If the plugin is a GtkButton, pressing it closes Status Menu.
 * First, all .desktop files are read, then plugins are loaded and laid out in the priority order.
 * The dynamic object file name determines the name of the plugin (name should be used in debugging and D-Bus names).



Hildon Input Methods
The Hildon input method system is architecturally separated from the rest of the Desktop domain, and it does not require any special handling in the window manager in Fremantle.

Fremantle will not have the partial-screen virtual keyboard anymore, only the full-screen on-screen keyboard and hardware keyboard. (MORE INFO NEEDED)

Clipboard manager
The Clipboard manager implements a clipboard manager for X window applications. It is taken from Diablo and the changes are kept minimal.

Configuration and Customization
The following subsections indicate how the UI framework is configured.

Theme configuration
The current theme is speciﬁed by /etc/hildon/theme symbolic link (by default it points to /usr/share/themes/default). The value of /etc/hildon/theme is also reﬂected in the MB_THEME property on the root window. The system default theme is speciﬁed by /usr/share/themes/default symbolic link. The system default theme must be present at all times because it is used as a fallback theme in case the user tries to switch to an invalid theme, and when restoring original settings from Control Panel.

When the user changes the theme using the Control Panel theme applet, the applet changes /etc/hildon/theme to point to the new theme, and hildon-desktop adjusts MB_THEME accordingly. hildon-desktop will set MB_THEME also when it starts up. The applications should use /etc/hildon/theme or MB_THEME to determine the currently selected theme.

Task launcher conﬁguration
The Task launcher is populated with applications that have installed their desktop ﬁles in the /usr/share/applications/hildon directory, as it is in Diablo. Layout of Task launcher is speciﬁed in a XML ﬁle inspired by the freedesktop.org Desktop Menu Specification 1.0. It will be stored in /etc/xdg/menus/applications.menu and, in case it is modiﬁed, in $HOME/.config/menus/applications.menu.

Home applet conﬁguration
Pre-installed conﬁguration ﬁles and the user deﬁne the Home applet conﬁguration. There are three conﬁguration ﬁles specifying the system-default conﬁguration:
 * /etc/hildon-desktop/home.conf
 * /etc/hildon-desktop/home.plugins and
 * /etc/hildon-desktop/home.safe-set

home.conf speciﬁes the directory for Home applets desktop ﬁles (default: /usr/share/applications/hildon-home) and the plugin conﬁguration ﬁle (default: /etc/hildon-desktop/home.plugins).

home.plugins speciﬁes the plugins which should be loaded when hildon-home starts, it simply lists the desktop ﬁles of the plugins. home.safe-set lists plugins which are included in the “safe set” of plugins; these applets will be loaded always (they must also be included in home.plugins), unlike the other plugins which are not loaded if hildon-home crashes and restarts.

/etc/hildon-desktop/home.plugins can be overridden with $HOME/.config/hildon-desktop/home.plugins, which is created when the user changes conﬁguration of loaded applets.

Status menu plugin conﬁguration
There are two pre-installed conﬁguration ﬁles specifying the system-default status menu plugins:
 * /etc/hildon-desktop/status-menu.conf and
 * /etc/hildon-desktop/status-menu.plugins

The ﬁrst one speciﬁes the directory from where Status menu plugins desktop ﬁles can be found (default: /usr/share/applications/hildon-status-menu) and the ﬁle deﬁning the “safe set” of plugins (default: /etc/hildon-desktop/status-menu.plugins). Normally Status menu loads all plugins listed in status-menu.plugins and all plugins that have installed a desktop ﬁle to the above mentioned directory; however, if Status menu crashes and restarts, it only loads plugins listed in status-menu.plugins.