• Intro
• Downloads
• Community
• Development
• News
• TALK

Documentation/Maemo 5 Developer Guide/Architecture/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, notification service, Hildon Home (applet loader), Hildon Status Menu/Area (plugin loader), and Status Menu USB plugin.

[edit] System Decomposition view

[edit] Subsystems in UI framework domain

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] Shutdown signal

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

[edit] 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 flags 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 flag.

The flag 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 flagged 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.

[edit] Hardware keyboard key bindings

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

[edit] 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.

[edit] hildon-home

The hildon-home process implements loading of Home applets, notification 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 flags the applet windows with specific 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 notifications on the screen, based on a proposed freedesktop.org Desktop Notification Specification6 . Typical notifications are incoming e-mails, chat messages, and missed phone calls. The service supports persistent notifications that are retained over a reboot, simple dialogs with return values, and queueing of notifications. It is also possible to install plugins for the notification service, e.g. to support sound and vibration effects in connection to notifications.

[edit] Notification D-Bus service

The hildon-home process provides the Desktop Notification Specification 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.Notifications interface recognises the following two additional messages for backwards compatibility.

[edit] 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’ Notifications 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 notification.

[edit] 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’ Notifications 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 notification. The dialog’s return value can be retrieved by listening to the NotificationClosed signal that bears the ID.

[edit] Notification plugin interface

The notification service supports plugins for e.g. sound and vibration functionality. The plugin code is not allowed to block.

[edit] 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=true
X-Text-Domain=gettextdomain
X-Display-On-All-Views=no

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

<?xml version="1.0" encoding="UTF-8"?>
<gconfschemafile xmlns:confml="http://www.s60.com/xml/confml/2">
  <schemalist>
    <!--Settings for calendar-home-applet.desktop-->
    <!--Home view where shortcut is visible-->
    <schema>
      <key>/schemas/apps/osso/hildon-desktop/applets/calendar-home-applet.desktop/view</key>
      <applyto>/apps/osso/hildon-desktop/applets/calendar-home-applet.desktop/view</applyto>
      <type>int</type>
      <default>1</default>
      <locale name="C"/>
    </schema>
    <!--Position of shortcut-->
    <schema>
      <key>/schemas/apps/osso/hildon-desktop/applets/calendar-home-applet.desktop/position</key>
      <applyto>/apps/osso/hildon-desktop/applets/calendar-home-applet.desktop/position</applyto>
      <type>list</type>
      <list_type>int</list_type>
      <default>[10,20]</default>
      <locale name="C"/>
    </schema>
  </schemalist>
</gconfschemafile>

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).

[edit] API for creating Web bookmarks

The libhildondesktop library provides function hd_shortcuts_add_bookmark_shortcut() for adding a Web bookmark shortcut on Home.

[edit] 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 configuration. 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-configured limit for the maximum number of plugin icons.

[edit] 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).

[edit] 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)

[edit] Clipboard manager

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

[edit] Configuration and Customization

The following subsections indicate how the UI framework is configured.

[edit] Theme configuration

The current theme is specified by /etc/hildon/theme symbolic link (by default it points to /usr/share/themes/default). The value of /etc/hildon/theme is also reflected in the MB_THEME property on the root window. The system default theme is specified 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.

[edit] Task launcher configuration

The Task launcher is populated with applications that have installed their desktop files in the /usr/share/applications/hildon directory, as it is in Diablo. Layout of Task launcher is specified in a XML file 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 modified, in $HOME/.config/menus/applications.menu.

[edit] Home applet configuration

Pre-installed configuration files and the user define the Home applet configuration. There are three configuration files specifying the system-default configuration:

• /etc/hildon-desktop/home.conf
• /etc/hildon-desktop/home.plugins and
• /etc/hildon-desktop/home.safe-set

home.conf specifies the directory for Home applets desktop files (default: /usr/share/applications/hildon-home) and the plugin configuration file (default: /etc/hildon-desktop/home.plugins).

home.plugins specifies the plugins which should be loaded when hildon-home starts, it simply lists the desktop files 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 configuration of loaded applets.

[edit] Status menu plugin configuration

There are two pre-installed configuration files specifying the system-default status menu plugins:

• /etc/hildon-desktop/status-menu.conf and
• /etc/hildon-desktop/status-menu.plugins

The first one specifies the directory from where Status menu plugins desktop files can be found (default: /usr/share/applications/hildon-status-menu) and the file defining 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 file to the above mentioned directory; however, if Status menu crashes and restarts, it only loads plugins listed in status-menu.plugins.