Editing Documentation/Maemo 5 Developer Guide/Architecture/UI Framework

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

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.

==System Decomposition view==

===Subsystems in UI framework domain===

{| class="wikitable"
|+ Subsystems in UI framework domain
|-
! Subsystem !! Function
|-
| [[#hildon-desktop|hildon-desktop]] || OpenGL graphics API
|-
| [[#hildon-home|hildon-home]] || Home widget API and loading, notification service and plugins, background image and loading
|-
| [[#hildon-status-menu|hildon-status-menu]] || X clipboard selection management
|-
| [[#Hildon Input Methods|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
|}

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

[[Image:hildon-desktop_decomposition.png|800px|alt=UML diagram|Hildon-desktop descomposition]]

====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 <code>hildon_program_set_can_hibernate()</code> function in the libhildon1 library.

The background killing signals are defined as follows:

{| class="wikitable"
|+ Background kill state on
|-
! Attribute !! Value
|-
| service || (ignored)
|-
| interface || <code>com.nokia.ke_recv.bgkill_on</code>
|-
| object path || <code>/com/nokia/ke-recv/bgkill_on</code>
|-
| member || <code>bgkill_on</code>
|}

{| class="wikitable"
|+ Background kill state off
|-
! Attribute !! Value
|-
| service || (ignored)
|-
| interface || <code>com.nokia.ke_recv.bgkill_off</code>
|-
| object path || <code>/com/nokia/ke-recv/bgkill_off</code>
|-
| member || <code>bgkill_off</code>
|}

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.

{| class="wikitable"
|+ Low-memory background kill state on
|-
! Attribute !! Value
|-
| service || (ignored)
|-
| interface || <code>com.nokia.ke_recv.lowmem_on</code>
|-
| object path || <code>/com/nokia/ke-recv/lowmem_on</code>
|-
| member || <code>bgkill_off</code>
|}

{| class="wikitable"
|+ Low-memory background kill state off
|-
! Attribute !! Value
|-
| service || (ignored)
|-
| interface || <code>com.nokia.ke_recv.lowmem_off</code>
|-
| object path || <code>/com/nokia/ke-recv/lowmem_off</code>
|-
| member || <code>bgkill_off</code>
|}

====D-Bus signal for closing applications====

The hildon-desktop process will listen to the <code>exit</code> D-Bus signal. When it catches the signal, it sends the (POSIX) <code>TERM</code> signal to all running windowed applications. This is used by the [[Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Using Backup Application|Backup application]] before restoring backed up data and settings, Backup itself can ignore the <code>TERM</code> signal. The signal is not meant to be used outside of the application framework.

{|class="wikitable"
|+ Exit signal
|-
! Attribute !! Value
|-
| service || (ignored)
|-
| interface || <code>com.nokia.osso_app_killer</code>
|-
| object path || <code>/com/nokia/osso_app_killer</code>
|-
| member || <code>exit</code>
|}

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

{| class="wikitable"
|+ Application died signal
|-
! Attribute !! Value
|-
| service || (ignored)
|-
| interface || <code>org.maemo.launcher</code>
|-
| object path || <code>org/maemo/launcher</code>
|-
| member || Application Died
|}

{| class="wikitable"
|+ Application died signal arguments
|-
! Argument # !! Mandatory !! Type !! Value
|-
| 1 || yes || <code>DBUS_TYPE_STRING</code> || ﬁle name of the executable
|-
| 2 || yes || <code>DBUS_TYPE_INT32</code> || PID of the died process
|-
| 3 || yes || <code>DBUS_TYPE_INT32</code> || exit code returned from <code>waitpid()</code>
|}

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

{| class="wikitable"
|+ D-Bus API to switch from fullscreen view to task switcher
|-
! Attribute !! Value
|-
| service || (ignored)
|-
| interface || <code>com.nokia.hildon_desktop</code>
|-
|| object path || (ignored)
|-
| member || <code>exit_app_view</code>
|}

====Shutdown signal====

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

{| class="wikitable"
|+ Shutdown signal
|-
! Attribute !! Value
|-
| service || (ignored)
|-
| interface || <code>com.nokia.mce.signal</code>
|-
| object path || <code>com/nokia/mce/signal</code>
|-
| member || <code>shutdown_ind</code>
|}

====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 <code>/apps/osso/keybindings</code> 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 <code>gtk_window_fullscreen()</code> and <code>gtk_window_unfullscreen()</code> functions. The WM will see the desired mode from a window property. See the [http://library.gnome.org/devel/gtk/stable/GtkWindow.html#gtk-window-fullscreen 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.

[[Image:hildon-home_components.png|1000px|alt=UML diagram|hildon-home components]]

===Notification D-Bus service===

The hildon-home process provides the Desktop Notiﬁcation Speciﬁcation D-Bus API documented in [http://www.galago-project.org/specs/notification/0.9/notification-spec-0.9.txt specification]. Notification can be specified to be persistent over device reboots by giving the ‘persistent’ hint in the D-Bus message.

The <code>org.freedesktop.Notiﬁcations</code> 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 <code>osso_system_note_infoprint()</code>. The ’standard’ Notiﬁcations API should be preferred over this for new applications.

{| class="wikitable"
|+ System information banner D-Bus API
|-
! Attribute !! Value
|-
| service || <code>org.freedesktop.Notifications</code>
|-
| interface || <code>org.freedesktop.Notifications</code>
|-
| object path || <code>/org/freedesktop/Notifications</code>
|-
| member || <code>SystemNoteInfoprint</code>
|}

{| class="wikitable"
|+ System information banner D-Bus API arguments
|-
! Argument # !! Mandatory !! Type !! Value
|-
| 1 || yes || <code>DBUS_TYPE_STRING</code> || message to show
|}

The return value is of the type <code>DBUS_TYPE_UINT32</code>, 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 <code>osso_system_note_dialog()</code>. The ‘standard’ Notiﬁcations API should be preferred over this for new applications.

{| class="wikitable"
|+ System information note D-Bus API
|-
! Attribute !! Value
|-
| service || <code>org.freedesktop.Notifications</code>
|-
| interface || <code>org.freedesktop.Notifications</code>
|-
| object path || <code>/org/freedesktop/Notifications</code>
|-
| member || <code>SystemNoteDialog</code>
|}

{| class="wikitable"
|+ System information note D-Bus API arguments
|-
! Argument # !! Mandatory !! Type !! Value
|-
| 1 || yes || <code>DBUS_TYPE_STRING</code> || message to show
|-
| 2 || yes || <code>DBUS_TYPE_UNIT32</code> || type of dialog, one of <code>OSSO_GN_*</code>
|-
| 3 || yes || <code>DBUS_TYPE_STRING</code> || label of the button
|}

The return value is of the type <code>DBUS_TYPE_UINT32</code>, it is the ID of the notiﬁcation. The dialog’s return value can be retrieved by listening to the <code>NotiﬁcationClosed</code> 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 <code>HDHomePluginItem</code> GObject class. <code>HDHomePluginItem</code> is a descendant of <code>GtkWindow</code>, so to add a widget to the Home applet, you should use the <code>gtk_container_add()</code> 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:
** <code>const gchar *hd_home_plugin_item_get_dl_filename (HDHomePluginItem *item);</code>
** <code>DBusConnection *hd_home_plugin_item_get_dbus_connection ( HDHomePluginItem *item, DBusBusType type, DBusError *error);</code>
** <code>DBusGConnection *hd_home_plugin_item_get_dbus_g_connection ( HDHomePluginItem *item, DBusBusType type, GError **error);</code>
** <code>guint hd_home_plugin_item_heartbeat_signal_add ( HDHomePluginItem *item, guint mintime, guint maxtime, GSourceFunc source_func, gpointer data, GDestroyNotify destroy);</code>
** <code>void hd_home_plugin_item_set_settings (HDHomePluginItem *item, gboolean settings); /* Whether the applet supports settings */</code>
** <code>gchar *hd_home_plugin_item_get_applet_id (HDHomePluginItem *item);</code>

Applet should install a desktop file, e.g.:
<pre>
[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
</pre>

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

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<gconfschemafile xmlns:confml="http://www.s60.com/xml/confml/2">
  <schemalist>
    
    
    <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>
    
    <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>
</source>

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 (<code>/etc/hildon-desktop/home.plugins</code> or <code>~/.config/hildon-desktop/home.plugins</code>).

===API for creating Web bookmarks===

The libhildondesktop library provides function <code>hd_shortcuts_add_bookmark_shortcut()</code> 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 <code>HDStatusMenuItem</code> (subclass of <code>HDStatusPluginItem</code>, which is subclass of <code>GtkBin</code>) <code>GObject</code> class, which has these class methods inherited from <code>HDStatusPluginItem</code>:
** Function for setting (or changing) the Status Area icon (<code>GdkPixbuf</code>): <code>hd_status_plugin_item_set_status_area_icon()</code>, <code>::status-area-icon</code> property
** Function for setting <code>GtkWidget</code> instead of <code>GdkPixbuf</code> as the Status Area icon: <code>void hd_status_plugin_item_set_status_area_widget ( HDStatusPluginItem *item, GtkWidget*widget);</code>
** Function for registering callbacks using the system-wide synchronized timers: <code>hd_status_plugin_item_heartbeat_signal_add()</code>
** Function for getting name of the plugin file, e.g. ''get_dlfilename: <code>hd_status_plugin_item_get_dl_filename()</code>, <code>::dl-filename</code> property
** <code>DBusConnection *hd_status_plugin_item_get_dbus_connection ( HDStatusPluginItem *item, DBusBusType type, DBusError *error);</code>
** <code>DBusGConnection *hd_status_plugin_item_get_dbus_g_connection ( HDStatusPluginItem * item, DBusBusType type, GError **error);</code>
* <code>HD_DEFINE_PLUGIN_MODULE</code> macro is used to define the plugin class as subclass of <code>GTypeModule</code>.
* Plugin widget's standard <code>GObject</code> constructor and destructor are used.
* Widget's visibility (in ''Gtk'') is used to show and hide the plugin.
* If the plugin is a <code>GtkButton</code>, 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).

[[Image:hildon-statusmenu_decomposition.png|800px|alt=UML diagram|hison-status-menu decomposition]]

==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 <code>/etc/hildon/theme</code> symbolic link (by default it points to <code>/usr/share/themes/default</code>). The value of <code>/etc/hildon/theme</code> is also reﬂected in the <code>MB_THEME</code> property on the root window. The system default theme is speciﬁed by <code>/usr/share/themes/default</code> 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 <code>/etc/hildon/theme</code> to point to the new theme, and hildon-desktop adjusts <code>MB_THEME</code> accordingly. hildon-desktop will set <code>MB_THEME</code> also when it starts up. The applications should use <code>/etc/hildon/theme</code> or <code>MB_THEME</code> 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 
<code>/usr/share/applications/hildon</code> 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 <code>/etc/xdg/menus/applications.menu</code> and, in case it is modiﬁed, in <code>$HOME/.config/menus/applications.menu</code>.

===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: 
* <code>/etc/hildon-desktop/home.conf</code>
* <code>/etc/hildon-desktop/home.plugins</code> and
* <code>/etc/hildon-desktop/home.safe-set</code>

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

<code>home.plugins</code> 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.

<code>/etc/hildon-desktop/home.plugins</code> can be overridden with <code>$HOME/.config/hildon-desktop/home.plugins</code>, 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: 
* <code>/etc/hildon-desktop/status-menu.conf</code> and 
* <code>/etc/hildon-desktop/status-menu.plugins</code>

The ﬁrst one speciﬁes the directory from where Status menu plugins desktop ﬁles can be found (default: <code>/usr/share/applications/hildon-status-menu</code>) and the ﬁle deﬁning the “safe set” of plugins (default: <code>/etc/hildon-desktop/status-menu.plugins</code>). 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.

[[Category:Development]]
[[Category:Documentation]]
[[Category:Fremantle]]

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Retrieved from "http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Architecture/UI_Framework"

Personal tools

Navigation

Views

Editing Documentation/Maemo 5 Developer Guide/Architecture/UI Framework

@@ Line 43: / Line 43: @@
 ====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 [[Documentation/Maemo 5 Developer Guide/Architecture/Data Management|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 <code>hildon_program_set_can_hibernate()</code> function in the libhildon1 library.
+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 <code>hildon_program_set_can_hibernate()</code> function in the libhildon1 library.
 The background killing signals are defined as follows: