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
Subsystem | Function |
---|---|
hildon-desktop | OpenGL graphics API |
hildon-home | Home widget API and loading, notification service and plugins, background image and loading |
hildon-status-menu | X clipboard selection management |
Hildon Input Method | Localized text input UI |
Control Panel | Control Panel applet and loading |
Startup Wizard | first boot and system time setting |
Startup scripts | AF startup scripts |
RFS and CUD framework | Reset factory settings and clear user data |
i18n data | POSIX data |
[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:
Attribute | Value |
---|---|
service | (ignored) |
interface | com.nokia.ke_recv.bgkill_on
|
object path | /com/nokia/ke-recv/bgkill_on
|
member | bgkill_on
|
Attribute | Value |
---|---|
service | (ignored) |
interface | com.nokia.ke_recv.bgkill_off
|
object path | /com/nokia/ke-recv/bgkill_off
|
member | bgkill_off
|
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.
Attribute | Value |
---|---|
service | (ignored) |
interface | com.nokia.ke_recv.lowmem_on
|
object path | /com/nokia/ke-recv/lowmem_on
|
member | bgkill_off
|
Attribute | Value |
---|---|
service | (ignored) |
interface | com.nokia.ke_recv.lowmem_off
|
object path | /com/nokia/ke-recv/lowmem_off
|
member | bgkill_off
|
[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.
Attribute | Value |
---|---|
service | (ignored) |
interface | com.nokia.osso_app_killer
|
object path | /com/nokia/osso_app_killer
|
member | exit
|
[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.
Attribute | Value |
---|---|
service | (ignored) |
interface | org.maemo.launcher
|
object path | org/maemo/launcher
|
member | Application Died |
Argument # | Mandatory | Type | Value |
---|---|---|---|
1 | yes | DBUS_TYPE_STRING | file name of the executable |
2 | yes | DBUS_TYPE_INT32 | PID of the died process |
3 | yes | DBUS_TYPE_INT32 | exit code returned from waitpid()
|
[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.
Attribute | Value |
---|---|
service | (ignored) |
interface | com.nokia.hildon_desktop
|
object path | (ignored) |
member | exit_app_view
|
[edit] Shutdown signal
hildon-desktop catches the following D-Bus signal on the system bus.
Attribute | Value |
---|---|
service | (ignored) |
interface | com.nokia.mce.signal
|
object path | com/nokia/mce/signal
|
member | shutdown_ind
|
[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.
Attribute | Value |
---|---|
service | org.freedesktop.Notifications
|
interface | org.freedesktop.Notifications
|
object path | /org/freedesktop/Notifications
|
member | SystemNoteInfoprint
|
Argument # | Mandatory | Type | Value |
---|---|---|---|
1 | yes | DBUS_TYPE_STRING | message to show |
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.
Attribute | Value |
---|---|
service | org.freedesktop.Notifications
|
interface | org.freedesktop.Notifications
|
object path | /org/freedesktop/Notifications
|
member | SystemNoteDialog
|
Argument # | Mandatory | Type | Value |
---|---|---|---|
1 | yes | DBUS_TYPE_STRING | message to show |
2 | yes | DBUS_TYPE_UNIT32 | type of dialog, one of OSSO_GN_*
|
3 | yes | DBUS_TYPE_STRING | label of the button |
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 ofGtkWindow
, so to add a widget to the Home applet, you should use thegtk_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 ofHDStatusPluginItem
, which is subclass ofGtkBin
)GObject
class, which has these class methods inherited fromHDStatusPluginItem
:- 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 ofGdkPixbuf
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);
- Function for setting (or changing) the Status Area icon (
-
HD_DEFINE_PLUGIN_MODULE
macro is used to define the plugin class as subclass ofGTypeModule
. - 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.
- This page was last modified on 2 March 2011, at 14:12.
- This page has been accessed 42,682 times.