ApiChangesSciroccoBoraHerring
- API changes from Maemo 2.1 Scirocco to Maemo 3.0 Bora, and Herring
- Introduction
- Hildon, Gtk, libosso (all in Herring)
- Telepathy and stuff
- Multimedia Changes (alsa stuff in Herring but not gstreamer update)
- Games framework (not yet in Herring)
- Maemo AF Desktop Status Bar Plugins (in Herring)
- State Saving, Autosaving and Background Killing (in Herring)
- Connectivity (Bluetooth in Herring)
- OSSO Help (in Herring)
- Control Panel Plugins (in Herring)
- Themeing
- Maemo AF Desktop Navigator Plugins (in Herring)
- Maemo Certificate Manager (partially in Herring)
- X (in Herring)
API changes from Maemo 2.1 Scirocco to Maemo 3.0 Bora, and Herring
Attention, this is an unfinished draft
MoinMoinWiki Macro: TableOfContents
still missing
- dbus: something about that?
- same upstream version (0.61-osso13fix->0.61-osso18). According to changelogs, only bug fixes added.
- Telepathy, Galago, ...
- Libossomime?
- do old status bar plugins work with the new status bar?
- EAP gconf keys have been changed since SDK2.0
- theming from (Johan?).
- gstreamer
Introduction
This document describes the API related changes between Maemo 2.1 Scirocco and Maemo 3.0 Bora. The document is sectioned in such a way that the most important changes are in the first sections and changes to less used features are in the latter sections.
Hildon, Gtk, libosso (all in Herring)
Package name | 2.0 | 2.1 | 3.0 |
---|---|---|---|
hildon-libs-dev | 0.12.20-1 | N/A | 0.14.2-1 |
hildon-base-lib-dev | 0.9.4-1 | N/A | 0.10.2-1 |
hildon-fm-dev | 0.28-2 | N/A | 1.9-1 |
libosso-dev | 1.14-1 | N/A | 1.17-1 |
libgtk2.0-dev | 2.6.10-1.osso21 | N/A | 2.6.10-2.osso13 |
libglib2.0-dev | 2.8.6-1osso5 | N/A | 2.8.6-1osso7 |
All 2.1 applications should compile and run cleanly. There are no changes, only additions, to the public 2.1 API concerning basic Maemo features like widgets and application launching.
It is not binary compatible, however. At least hildon-fm and libhildonmenu break the compability.
New Features (all in Herring)
Hildon widget library contains a new set of widgets for selecting a color. There is a chooser widget, chooser dialog and a chooser button. There is also a new plugin widget API which the new color chooser widget set uses.
See https://stage.maemo.org/svn/maemo/projects/haf/tags/hildon-libs/0.14.2-1/doc/design/hildon-plugin-widget.txt for more information about the plugin widget
List of new headers in Hildon library: * hildon-widgets/hildon-color-chooser.h * hildon-widgets/hildon-color-chooser-button.h * NOTE: No GTK API documentation! * hildon-widgets/hildon-color-chooser-dialog.h * hildon-widgets/hildon-plugin-widget.h
Desktop files for applications contain two new fields, "comment" and "x-text-domain". The "comment"-field is a comment or a short description of the application and can be shown in e.g. tooltips or in thumb menu in addition to the application name. The "x-text-domain" is used to tell the text domain for translations. If the "x-text-domain" is not provided the "maemo-af-desktop" domain will be used. By setting this to the applications own domain it can provide the translations for the name in it's own package.
Libosso has some minor changes.
The osso_time_set()
now actually sends a notification about a time change (it does not change the time, however).
Functions osso_display_state_on()
and osso_display_blanking_pause()
can return also OSSO_INVALID
in case of invalid parameters.
Removed Features (from Herring too)
Function _hildon_file_system_model_load_children()
is removed from the Hildon FM header "hildon-file-system-model.h".
It was already commented as not for public use.
Telepathy and stuff
TODO
Multimedia Changes (alsa stuff in Herring but not gstreamer update)
Package name | 2.0 | 2.1 | 3.0 |
---|---|---|---|
osso-mediaengine | N/A | 1.2.12-1(w37) | |
libgstreamer-plugins-base0.10-dev | N/A | N/A | 0.10.9-osso |
libgstreamer0.10-dev | 0.10.5-osso1 | N/A | 0.10.9-osso2 |
osso-esd | 0.17-1 | N/A | 0.51-1 |
libasound2-dev | - | N/A | 1.0.10-osso5 |
The multimedia framework has some updates. GStreamer has been upgraded from upstream version 0.10.5 to 0.10.9 (see the changelogs below) and a few GStreamer plugins has been added (see the list below).
Limited ALSA support has been added for better compability with 3rd party applications. ESD is still supported and used e.g. by Hildon widgets.
GStreamer changelogs: * http://gstreamer.freedesktop.org/releases/gstreamer/0.10.6.html * http://gstreamer.freedesktop.org/releases/gstreamer/0.10.7.html * http://gstreamer.freedesktop.org/releases/gstreamer/0.10.8.html * http://gstreamer.freedesktop.org/releases/gstreamer/0.10.9.html
New Features (in Herring but not tested)
The ALSA PCM plugin is described in https://garage.maemo.org/projects/dsp-alsa/. The ALSA support in Maemo includes the ALSA libraries but not ALSA plugins for the GStreamer since applications should still use the DSP PCM or DSP decoder plugins for playback.
Games framework (not yet in Herring)
Package name | SDK2.0 | SDK2.1rc8 | SDK2.1 | SDK3.0alpha |
---|---|---|---|---|
maemo-games-startup-dev | 0.1.5 | 0.1.5 | N/A | 0.1.5 |
libsdl1.2-dev | 1.2.8-10 | 1.2.8-10 | N/A | 1.2.8-13 |
libsdl-net1.2-dev | 1.2.5-osso1 | 1.2.5-osso1 | N/A | 1.2.5-osso1 |
The game framework has not changed much. The maemo games startup package is still the same. SDL library uses now ALSA as the audio backend instead of the ESD.
Maemo AF Desktop Status Bar Plugins (in Herring)
TODO: does new SB support old plugins?
The Status Bar API has been altered slightly after 2.1. In 3.0 the Status Bar supports three different kind of plugins: permanent, conditional and temporal. Permanent plugins are shown all the time. Conditional and temporal plugins are shown only when a condition is fulfilled. Also, now the user is able to select plugins and change plugins' positions from Control Panel.
The plugin API contains a new optional function [plugin_name]_set_conditional()
which can (will?) be used by Status Bar to set the status of the plugin.
There is also a new signal hildon_status_bar_update_conditional
with a boolean parameter that the plugin can send to Status Bar to update the conditional status.
There is also a new function for the temporary and conditional plugins: hildon_status_bar_item_set_button()
. These plugins can leave the button widget as NULL in the initialization and set it later with the new function.
Format of the 3.0 status bar plugins' .desktop file:
[Desktop Entry] Name=<logical name identifier> Icon=<logical icon identifier> Category=<permanent/conditional/temporal>, the default value is permanent if the key value read fails. X-status-bar-plugin=lib<plugin name>.so Mandatory=<true/false>, if not set, the default value is false
TODO: StatusBarAPIchange Statubar plugin API
== Maemo AF Desktop Home Plugins (in Herring)==
Package name | 2.0 | 2.1 | 3.0 |
---|---|---|---|
hildon-home-dev | 2.6.31-1 | N/A | 2.9.22.1-1 |
The Home plugin C API has not changed at all, but the Home now supports resizing of the plugins. The plugin can choose whether is is resizeable in X or Y direction and what is the minimum width and height of the plugin.
This new information is described in the plugin's .desktop file which has the following new format:
[Desktop Entry] Name=<logical_name> Comment=<engineering english name of applet> Type=HildonHomeApplet X-home-applet=lib<appletname>.so X-home-applet-resizable=[XY] X-home-applet-minwidth=width X-home-applet-minheight=height
minwidth/minheight tells the minimum resize size allowed and resizable defines which dimensions are allowed to resize.
If the new fields are missing then the Home treats the plugin as non-resizable, i.e. old Home plugins should work with the new API flawlessly.
State Saving, Autosaving and Background Killing (in Herring)
Package name | 2.0 | 2.1 | 3.0 |
---|---|---|---|
libosso-dev | 1.14-1 | N/A | 1.17-1 |
hildon-libs-dev | 0.12.20-1 | N/A | 0.14.2-1 |
The state saving, autosaving and background killing API have not changed. Only addition is a nice detailed doxygen documentation about state saving and autosaving in libosso.h. A link to this new information should be provided in Maemo.org documentation.
Connectivity (Bluetooth in Herring)
Package name | 2.0 | 2.1 | 3.0 |
---|---|---|---|
osso-bttools-dev | 0.34.4 | N/A | 0.40.3 |
libgwobex-dev | 0.47.4 | N/A | 0.53 |
osso-gwconnect-dev | N/A | N/A | 1.0 |
bluez-utils | N/A | N/A | 3.5osso2 |
conbtdialogs-dev | - | - | 1.4.1 |
TODO: Internet connectivity
The bluez-utils package has been upgraded to a new stable upstream version (from 2.25 to 3.5) which provides new DBUS calls to hcid.
The bluez-utils Changelog.
Removed Features
osso-bttools package provided a btname command line tool and a DBUS API for setting the BT name and BT pairing. It is now deprecated.
OSSO Help (in Herring)
Package name | 2.0 | 2.1 | 3.0 |
---|---|---|---|
libosso-help-dev | 1.5.11-1 | N/A | 2.0.6-1 |
The OSSO help library has two headers: osso-helplib-private.h and osso-helplib.h.
The latter one is public and has not been changed. The private version has two new functions, browser_focus_forward_backward()
and browser_has_focus()
.
The private header file comments the content as follows:
... these are exported but intended to be used by members of the Help clan (HelpUI, !HelpTest, HelpGS) only. Therefore, incompatible changes will be mercilessly implemented, if necessary.
No changes in the Help XML document syntax etc.
Control Panel Plugins (in Herring)
Package name | 2.0 | SDK2.1 | 3.0 |
---|---|---|---|
hildon-control-panel-dev | 1.2.5-1 | N/A | 2.2.5-1 |
The Control Panel plugins are now divided into categories and the layout is constructed based on those. The named categories are: general, connectivity, personalisation and extras.
The Control Panel plugin's .desktop file with the new "categories" field:
[Desktop Entry] Name=<logical applet name identifier> Comment=Control Panel Applet Type=HildonControlPanelPlugin Icon=<logical icon name identifier> Categories=<general/connectivity/personalisation/extras>, from which the extras is the default value, in case the key value read fails. X-control-panel-plugin=lib<applet name>.so
Old Control Panel plugins should work flawlessly and they should show up in the Extras category.
Themeing
TODO
Maemo AF Desktop Navigator Plugins (in Herring)
Package name | 2.0 | 2.1 | 3.0 |
---|---|---|---|
hildon-navigator-dev | 2.6.31-1 | N/A | 2.9.22.1-1 |
The Navigator plugin API has suffered only some cosmetic changes.
Mainly it seems that the includedir
field in pkgconfig file was wrong and now has been corrected (the proper include directory is hildon-navigator-dev
instead of hildon-navigator
).
New Features (in Herring)
The pkgconfig file for Navigator has now also plugindesktopentrydir
field for the plugins to acquire installation directory for the .desktop files.
There is a new widget: !HildonThumbMenuItem. It is meant for implementing a thumbable menu. It is a part of the libhildonmenu package to allow plugins to use it.
TODO: maemo-af-desktop/tn_thumbable_menu/ TODO: TaskNavigatorAPIchange
Removed Features (also from Herring)
The header file "hildon-navigator-interface.h" has been removed from the dev package. It seems that it was not meant for the Navigator plugins and was broken in anyway.
Maemo Certificate Manager (partially in Herring)
Package name | 2.0 | 2.1 | 3.0 |
---|---|---|---|
libosso-certman-dev | 1.5.13-1 | N/A | 2.0.2-1 |
libcst-dev | 1.6.34maemo1 | N/A | 1.7.1 |
The API that is meant to be public, libosso-certman-dev, has not changed.
The libcst-dev (not in herring) contains some small modifications in the headers. Although this API is described in the Maemo.org it is not meant to be used by the 3rd party developers as the primary Certificate Manager API.
Functions CST_is_purpose()
and CST_set_default()
has better documented return value, the function CST_open()
has clarification about mandatory GLIB initialization. A new function CST_all_CA()
has been introduced. And a bug documented in Maemo.org has been fixed: the CST_PURPOSE_ALL define has been increased from 0xffff to 0xffffffff.
X (in Herring)
X has been updated from the old xlibs tree, to current X.Org. All libxproto-foo-dev has been renamed to x11proto-foo-dev; most libxfoo-dev has been unchanged. pkg-config should now be used to search for X, i.e.:
$(pkg-config cflags libs x11 xi)
instead of searching for libX11 and libXi, or searching for certain includes under /usr/X11R6/include. The libraries and includes now live in /usr/lib and /usr/include/X11, respectively.