maemo.org wiki - User contributions [en]

MADDE/QtCreator integration for linux

Maemo — Wed, 24 Mar 2010 09:06:10 GMT

Maemo: moved QtCreator integration for linux to MADDE/QtCreator integration for linux

= QtCreator and MADDE on Linux =

This is a guide on how to enable MADDE in QtCreator. This is part of the technology preview. After following this guidance you are able to build your sources within QtCreator for your device, and deploy, run and debug your applications with few mouse clicks from your Linux installation (Ubuntu was used for this tutorial).

Requires:

* [[MADDE | MADDE]] installed on your Linux machine
* If you want to compile your code natively then you have to have "make" installed on your machine. If it is not install yet you can do that with:

sudo apt-get install make

== General advice ==
As this is a technology preview, remember that bugs can occur. If some of the components don't work as expected, please add your question to the [http://talk.maemo.org/showthread.php?t=46570 talk-thread] and follow up the discussion.

== Install latest QtCreator on your Linux computer ==

'''You cannot use the latest official QtCreator for this. The version has to be >= 1.3.80! For these instructions the version of the 2010-03-04 is used!''' Find the latest build of QtCreator for Linux here:

http://qt.nokia.com/developer/qt-snapshots

== Add Qt for Maemo5 ==

You can change the configuration of the Qt-version in your QtCreator installation by clicking:

QtCreator -> Preferences -> Qt4 -> Qt Versions

'''Tip:''' If you do not see any Qt version by default here, you most likely haven't installed the needed Qt libraries to compile your Qt application for your Linux environment.

In the next step you have to add the Qt version for Maemo5 to the configuration of QtCreator. It is needed to compile your sources for your Maemo device. Click on the "+" in the upper-right corner. The configuration form will ask you to enter a "Version name" and to locate "qmake". You can find it in your MADDE installation folder under:

<MADDE_folder>/targets/<target_name>/bin

For the '''standard installation''' it would be for example:

Version name: Maemo Qt4.5
qmake Location: /home/<username>/.madde/0.6.14/targets/fremantle-qt-0951/bin/qmake

'''Tip:''' You cannot find the folder if you click on "Choose...", as it is hidden. But after entering "/home/<username>/.madde/" in the text-field "qmake Location" you can select the rest via the "Choose..." button.

[[Image:01_linux_qtcreator_add_qmake.png|300px]] [[Image:02_linux_qtcreator_select_qmake.png|300px]]

Now you will see Qt for Maemo as a new Qt Version in Qt Creator. But first you will see the red cross next to the Qt Version in the column "Debugging Helper". The last step you have to do now is clicking on "Rebuild" and after a while (you can follow the status in the QtCreator main window) it should look like this:

[[Image:03_linux_qtcreator_qmake_rebuild.png|300px]] [[Image:04_linux_qtcreator_qmake_ready.png|300px]]

== Configure device run-time in Qt Creator ==

After setting up the connection between your Linux computer and your device, you will be able to compile, deploy, test and debug your application with a single mouse-click. The description shows the configuration for USB-networking and WLAN and is for each divided into two parts. It shows:

* what to install on device, and
* how to set-up your Linux machine

=== General device set-up ===

Please find the instructions on how to set up the device runtime from here:

* [[MADDE/QtCreator_integration_for_windows#Install_the_client | Install the client]]

=== Connect via USB-networking ===

==== Device configuration ====

The following guide shows you, what to do on your device to set up the USB connection. This has to be done '''before''' you connect your device with the Linux computer:

* [[MADDE/QtCreator_integration_for_windows#Configure_the_client_for_USB | Configure the client for USB networking]]

==== Linux configuration ====

Connect the device with your Linux machine. Then you click on "PC Suite mode" as connection mode. Now you should be able to see the device as a new wired network connection named "Auto usb0". Now you can configure the connection as follows.

1. Open the network connection settings:

[[Image:05_linux_network.png|400px]]

2. Change the method from "DHCP" to "Manual" and enter the details as shown in the screen-shot:

[[Image:06_linux_configure_usb.png|400px]]

After you have done this your connection should be established and the set-up ready to be used with QtCreator.

=== Connect via WLAN ===

If both devices are connected to the same wireless network the configuration is a bit easier, but be aware that the IP address might not be the same all the time. This effects the set up of your QtCreator configuration.

==== Device configuration ====

Please open the mad-developer application. If you are connected already to the wireless network, you can find the IP address in the initial window of the application:

[[Image:10_mac_mad-dev_wlan.png|300px]]

==== Linux configuration ====

Please just make sure, that your Linux computer and device are connected to the same network.

=== QtCreator Configuration ===

After the connection between your PC and the device is set up, you can configure QtCreator to deploy and run the built applications on device. You can add your device in the configuration. You will find it in:

QtCreator -> Preferences -> Qt4 -> Maemo Device Configurations

First get the password from the Mad Developer application. You get it by clicking on "Developer Password" in the main view. '''Be aware''' that each time you click on the button, a new password will be created and that the password is only valid for the time it is shown in the application.

[[Image:04_b_client_ready.png|300px]] [[Image:05_client_pw.png|300px]]

====Instructions for USB-network====

Add the password and all the data you see in the screenshot below. Check the box, that you want to use the password as the authentication method. After that click on "test" and see if the connection can be set up.

[[Image:07_linux_qtcreator_usb.png|300px]]

====Instructions for WLAN====

If your device is using the WLAN interface, please enter the IP address you can see in the mad-developer application on device.

[[Image:08_linux_qtcreator_wlan.png|300px]]

'''Tip''' You can use your ssh key for the connection. Click on "Deploy Key ..." and select your key. If the other settings are correct the key will be automatically deployed on your device, so that you don't have to worry about the passwords anymore.

=== Deploy SSH key ===

If you have already created a key for other purposes you don't have to create a new one and you can ignore the description on how to create the key and just continue with the deployment of the key.

==== Create a key ====

To create a key please open terminal and run:

ssh-keygen -t rsa -b 1024

Then please follow the instructions. If you don't choose a new location, the key will be stored in the standard location in the home folder (recommended). The terminal should look like this:

[[Image:09_linux_keygen.png|400px]]

==== Deploy the key from QtCreator ====

To be able to connect to your device by using the key, you have to:

* deploy your public key on your device, and
* specify in QtCreator, where to find the private key

You can configure these settings in the Maemo Device Configurations

Tools -> Options... -> Qt4 -> Maemo Device Configurations

'''Note: ''' For these steps your device has to be connected to the PC and the password has to be valid. By clicking "Test" button, you can check if that is the case.

Now you click on "Deploy..." and select the public key you have created before.

[[Image:10_linux_select_pubkey.png‎|300px]]

Once the key is deployed correctly you can set up your device-configuration to use the key to connect to the device. Change now the "Authentication type" from "Password" to "Key".

[[Image:11_linux_setkey.png‎|300px]]

Now click on "Apply" and your QtCreator installation is set up to connect to the device via SSH key.

== Use Maemo5 build settings ==

Now all the configuration is done and you can select Maemo as a build configuration. If you have a project, which you want to compile for Maemo, then click on the project button in the menu of the left side. Now you should seen a screen, like in the screen shot below. If you have the Qt libraries installed, then you will have the "Desktop" as the default option selected.

[[Image:12_linux_initial_config.png]]

'''Tip:'''

* It might be that you don't see the "Desktop" widget in your project configuration. In this case it might be that the configuration of the MADDE is not correct, or that a little bug prevents the widget from showing up. In this case click on "Dependencies" and then go back to "Build".

* If you start a new project you can add the Maemo build-configuration at the beginning:

:[[Image:13_linux_start_new_project.png|300px]]

Now press the plus in the widget, which shows, that "Desktop" is selected as default. This should open a new dialog, where you select "Maemo". After that you will find a new build-configuration. Now click in "Maemo" on "Run" and select your device, which you have configured before. In the example it was called Maemo 5.

[[Image:14_linux_select_device.png]]

Finally you can now set in the down left corner, which build configuration you want to use:

[[Image:15_linux_select_runtime.png]]

Now you can click on the run button, and your application will be automatically compiled for the Maemo device, delpoyed, and started.

[[Category:Development]]

Documentation/Maemo 5 Final SDK/Discover Maemo 5 SDK

Maemo — Tue, 06 Oct 2009 08:48:08 GMT

Maemo:

= Panorama Desktop =
[[Image:panaroma.png|500px]]

*Four virtual desktops or home screens
*Personalize each of the desktops to your content
*Slide through them with the click and drag gesture of the mouse

=Multi Tasking=
[[Image:TaskSwitcher.png|500px]]

*No longer view one application at a time.
*Active thumbnail view of all open applications.
*A button click to switch between open applications.

=Home Widgets=
[[Image:desktop.png|500px]]

*Add cool widgets to your home
*Develop new widgets
*[http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Application_Development/Writing_Desktop_Widgets#Home_Widgets Learn how to do them]
*[https://garage.maemo.org/svn/maemoexamples/trunk/example_desktop_widget/ Example clock widget]

=Web Browser=
[[Image:Browser.png|500px]]

*Full screen, 800X480 resolution
*Advanced interactive mode
*Recent browser history as thumbnails
*Mozilla browser engine
*Browser interface API (Debian Package:tablet-browser-interface)

=Email=
[[Image:email.png|500px]]

*Modest Email Client
*Easy setup of email accounts
*[http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Using_Data_Sharing/SendVia_Functionality Email interface API tutorial]
*[https://garage.maemo.org/svn/maemoexamples/trunk/maemopad/ Example code]

=Contacts=
[[Image:contacts.png|500px]]

*Smooth integration with VOIP and IM contacts
*Address Book API (LINK)
*[http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Using_Generic_Platform_Components/Using_Address_Book_API Tutorial]

=Calendar=
[[Image:calendar.png|500px]]

*Manage events
*Create multiple calendars
*Calendar interface API (LINK)

=Clock=
[[Image:clock.png|500px]]

*World clock
*Manage alarm events
*[http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Using_Generic_Platform_Components/Alarm_Framework Alarm Framework Tutorial]

=Photos=
[[Image:photoviewer.png|500px]]

*View images
*Simple edit functions
*Create new sharing plugins
*[http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Using_Data_Sharing/Sharing_Plug-in#Sharing_Plug-in_Creation Sharing Tutorial]
*Sharing plugin API (LINK)

=Application Manager=
[[Image:appmgr.png|500px]]

*Manage application catalogues
*Download new applications
*Update or remove installed applications

=Media Player=
[[Image:mediaplayer.png|500px]]

*Create playlists
*[http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Using_Multimedia_Components/Media_Application_Framework_(MAFW) Media Application Framework tutorial]
*APIs

=File Manager=
[[Image:filemanager.png|500px]]

*Manage ﬁles and folders
*File Management APIs (LINK)
*[https://garage.maemo.org/svn/maemoexamples/branches/fremantle-sdk-testing/maemo-examples/example_file_chooser.c Example code]

=Virtual Keyboard=
[[Image:vbk2.png|500px]]

*Ability to use virtual ﬁnger keyboard instead of hardware keys.
*[https://stage.maemo.org/svn/maemo/projects/haf/trunk/hildon-input-method-plugins-example/ Example code]

=Xterm=
[[Image:xterm.png|500px]]

*Console terminal

Documentation/Maemo 5 Developer Guide/Architecture/Imaging and Sharing

Maemo — Mon, 05 Oct 2009 17:41:54 GMT

Maemo: /* Imaging and Sharing High Level Architecture */

= Imaging and Sharing High Level Architecture=

Subsystems of Imaging and Sharing domain are implementing means to produce, review, change, and share photography content on the device.

Following user-accessible applications are provided by Imaging and Sharing domain:
* Camera Application is a graphical interface to camera hardware. It accesses OMAP3 camera HW subsystem through a GStreamer-based middleware.
* Image Viewer allows to view photographs and images and supports simple/basic image editing functionality.

Sharing subsystem provides direct integration to an extensible set of internet services like OVI, with simple interface for uploading (i.e. “sharing”) content e.g. images to those services.

The diagram below shows the main interfaces of the domain.

[[Image:Imaging_Sharing_sw_context.png|480px]] 
''Imaging and Sharing, Software Context''

==Interfaces provided==
{|border=1
|'''Interface'''
|'''Description'''
|-
|Image Viewer UI
|The primary user interface for viewing still images and manipulating them.
|-
|Sharing UI
|The user interface for sharing content via internet services such as Nokia’s OVI.
|-
|Camera UI
|The primary user interface for using the device’s camera for capturing still images and video.
|-
|GDigicam
|An abstraction over complex set of GStreamer pipelines used to perform still image and video capturing.
|-
|Sharing plug-in extensions
|An interface for external developers to extend Sharing subsystem's reach to internet services.
|-
|Viewing capability
|Image Viewer application is the device’s primary means to view images, and it thus launched when user wants to handle the associated image files.
|}

==System decomposition view==

===Camera application===
{|border=1
|'''Name'''
|'''Camera application'''
|-
|'''Purpose'''
|Implements the camera UI interface
|-
|'''Responsibilities'''
|
*Implements camera controls for end user (e.g. open, close, capture, zoom) 
*Implements camera settings (e.g. scene modes, flash settings etc.) 
*Implements indicators (e.g. shake indicator) 
*Implements main power management for camera
|-
|'''License'''
|Nokia
|}

====Interfaces provided====
{|border=1
|'''Interface name'''
|'''Dependency'''
|'''Description'''
|-
|GDigigcam
|GStreamer
|High-level model abstraction of a GStreamer-based pipelines to access camera features
|-
|GDIGICAM facade
|GDigicam
|Facade to interact with media objects in Camera UI
|-
|Gdigicam manager
|GStreamer
|Abstract interface over camera operations
|-
|Camerabin
|Multimedia framework
|Component to control camera pipeline on GStreamer level
|}

GDigicam library and Camerabin GStreamer element are provided as Free Software under LGPL2.1 in order to allow alternative implementations of certain image processing steps.

===Image Viewer===
{|border=1
|'''Name'''
|'''Image Viewer'''
|-
|'''Description'''
|A viewer like content management application.
|-
|'''Responsibilities'''
|
*Implements a simple and fast interface for context sensitive user interface for viewing and selecting and categorizing the images. 
*Supports viewing of single images, snapshot views based on selectable categories and image presentations.
|-
|'''Notes'''
|Image Viewer is a single instance application, only one viewer instance available at a time.
|-
|'''License'''
|Nokia
|}

====Interfaces provided====
{|border=1
|'''Interface'''
|'''Dependency'''
|'''Description'''
|-
|Viewing capability
|User
|User interface to access Image Viewer application functionality
|-
|Launch application
|D-Bus
|D-Bus interface to open the Image Viewer application, used by Camera, Browser, File Manager, Email.
|}

===Sharing===
{|border=1
|'''Name'''
|'''Sharing'''
|-
|'''Purpose'''
|Sharing subsystem implements means to upload a content originating on the device to internet-based social services.
|-
|'''Responsibilities'''
|
*Implements dialogs for uploading of images to supported internet services 
*Implements simple management (i.e. filtering, adding) of metadata for images to be shared 
*Implements an API for extensions to add support for new internet services 
|-
|'''Notes'''
|Sharing subsystem contributes libraries which are used from within the context of other applications. Image Viewer is a primary consumer of these services within Imaging and Sharing domain.
|-
|'''License'''
|Nokia. Plug-in API is available under LGPL2.1
|}

====Interfaces provided====
{|border=1
|'''Interface name'''
|'''Dependency'''
|'''Description'''
|-
|Sharing plugins API
|Plugins API for sharing components
|An API for adding support for new internet services
|}

Documentation/Maemo 5 Developer Guide/Architecture/Multimedia Domain

Maemo — Wed, 23 Sep 2009 12:43:30 GMT

Maemo: /* Gstreamer */

=Multimedia Domain=
The Multimedia Framework Domain is a combination of a Multimedia Framework (GStreamer), a sound server (PulseAudio), a policy subsystem (OHM and libplayback), codecs and algorithms (for ARM and DSP) , a small number of UIs (status menus and control panel applets) and various libraries (alsa).

It provides audio/video playback, streaming services, imaging and metadata gathering support. More in general, it takes care of the actual audio/video data handling (retrieval, demuxing, decoding and encoding, seeking …).

The clients of the Multimedia framework are the Multimedia Applications, RTC subsystem, and all the Linux applications/entities which produce sounds through the PulseAudio, ESD or ALSA interfaces and capture images from the V4L2 interface.
The Multimedia Framework subsystem is partially located on the user space of Linux and on the DSP.

[[Image:OMAP_architecture.png|800px]]

Major challenge for the Multimedia framework is to provide the same interfaces like on desktop Linux for different hardware platforms. In order to achieve this objective, the whole audio processing is moved to the ARM side (ALSA / PulseAudio) and OpenMAX IL is introduced to abstract the hardware specific components (codecs and other hardware accelerated elements).

==Video subsystem==

[[Image:mmf_video_decomposition.png]]

===Video Codecs===
Most of the video encoders and decoders are wrapped under the OpenMAX IL interface [OMAX], which abstracts the codec specific implementation (which in general can run on ARM or DSP). All the OpenMAX IL video codecs will be running on the DSP side in order to best exploit the HW acceleration provided by the OMAP 3430 platform. The DSP based OpenMAX IL components are loaded by TIs IL-Core, which in turn uses LCML and the DSP-Bridge. The ARM based OpenMAX IL are loaded via Bellagio IL-Core. Both IL-Cores are used by the gst-openmax bridge. The GStreamer framework resides on the ARM side.

Video post processing is performed on DSS screen accelerator. DSS is used to do the colorspace conversion, the scaling and composition, including overlays. A separate external graphics accelerator is used to refresh the screen. In case of need (complicated use cases) the scaling and colorspace conversion can be done on the ARM side as well, but that is not recommened as it is not optimized.
A/V synchronization is done on the ARM, using an audio clock that is based on information from the audio interface.

The communication between ARM and DSP software is provided by the TI DSP bridge. Any messages or data buffers exchanged between the ARM and DSP go through it. This layer can be regarded as transparent from Multimedia Architecture point of view and hence it will not be described in this document.

===GStreamer===
GStreamer is a crossplatform media framework, covering most multimedia applications use cases from playback, to streaming and imaging. It is a huge collection of objects, interfaces, libraries and plugins. From the application point of view it is just one utility library that can be used by applications to process media streams. The library interface is actually a facade to a versatile collection of dynamic modules that implement the actual functionality. GStreamer core hides the complexity of timing issues, synchronization, buffering, threading, streaming and other functionalities that are needed to produce usable media application.

When using GStreamer as a media playback framework, application developer is given a set of tools and building blocks for implementing the decoding engine. The framework provides actual decoding and data streaming services, but it is up to the user how to use these tools. Application logic and utilizing the services of GStreamer are tasks of the developer.

GStreamer was chosen as a base framework on the ARM side because of the following reasons:
*GStreamer is a development framework for creating applications like media players, video editors, streaming media broadcasters and so on.
*GStreamer’s development started back in 1999 and it is relatively a long living open source project. The releases are frequent so far.
*There are many famous open source codecs supported by GStreamer and some example players based on GStreamer are available.
*GStreamer developers have a close relationship with the GNOME community, which is a potential advantage later on.
*GStreamer is written in C, which can be an advantage in embedded systems.
*GStreamer provides good modularity and flexibility. Hence, building applications on GStreamer in short time is possible.
*GStreamer is LGPL and it allows Multimedia Project to combine GStreamer with proprietary software.

====Public interfaces provided by GStreamer====
{|cellspacing="0" border="1" width="70%"
|'''Interface name'''||'''Description'''
|-
|GStreamer API||Interface for Multimedia applications, VOIP etc
|-
|playbin||Recommended high level element for playback.
|-
|uricodebin||Recommended high level element for decoding.
|-
|tagreadbin||Recommended high level element for fast metadata reading.
|-
|camerabin||Recommended high level element for camera application.
|}

===OpenMAX IL===
OpenMAX is an effort to provide an industry standard for a multimedia API. The standard defines 3 layers – OpenMAX DL (Development Layer), OpenMAX IL (Integration Layer) and OpenMAX AL (Application Layer). DL is a vendor specific and optional component. IL is the layer that interfaces with IL components (e.g. codecs). We will integrate TI IL-Core for the DSP components and Bellagio IL-Core for ARM components. Neither of the cores uses DL.
We use GStreamer’s gomx module to transparently make OpenMAX IL components available to any GStreamer application.

====TI OpenMAX IL Core====
{|cellspacing="0" border="1" width="70%"
|'''Purpose'''||OpenMAX IL Core implementation for DSP.
|-
|'''Responsibilities'''||Provides media handling services.
|-
|'''License'''||TI
|}

====Bellagio OpenMAX IL Core====
{|cellspacing="0" border="1" width="70%"
|'''Purpose'''||Generic OpenMAX IL Core implementation (used on ARM side)
|-
|'''Responsibilities'''||Provides media handling services.
|-
|'''License'''||LGPL
|}

==Imaging subsystem==
The multimedia framework also provides support for imaging applications. The subsystem is illustrated below.

[[Image:Imaging_decomposition.png|800px]]

===Camera Source===
The GstV4L2CamSrc is a fork of the GstV4l2Src plugin. The reason for the fork is that the original plugin has lots of extra code for handing various V4L2 devices (such as tuner crads) and that made the code quite complex.

====GStreamer V4L2 Camera Source====
{|cellspacing="0" border="1" width="70%"
|'''Purpose'''||Image and Video capture
|-
|'''Responsibilities'''||Capture RAW and YUV image
|-
|'''License'''||LGPL
|-
|'''Packages'''||gstreamer0.10-plugins-camera
|}

===Image Codecs and Filters===
The image encoders and decoders are wrapped under the OpenMAX IL interface [OMAX], which abstracts the codec specific implementation (which in general can run on ARM or DSP). All the image codecs will be running on the DSP side to best exploit the HW acceleration provided by the OMAP 3430 platform.
The post processing filters needed for the camera application will be implemented as GStreamer elements and will run on the DSP.

===Camera Daemon===
The camera daemon is holding imaging specific extensions to the v4l2 interface. Specifically it runs the so called 3A algorithms – AutoFocus (AF), AutoWhitebalance (AWB) and AutoExposure (AE).

{|cellspacing="0" border="1" width="70%"
|'''Name'''||Camera Daemon
|-
|'''Purpose'''||Control imaging specific aspect not yet covered by standard v4l2
|-
|'''Responsibilities'''||Runs 3A algorithms
|-
|'''License'''||Nokia
|}

====Public interface provided by camera daemon====
{|cellspacing="0" border="1" width="70%"
|'''Interface name'''||'''Description'''
|-
|V4L2 ioctl||Extensions for V4L2 protocol
|}

==Audio Subsystem==

[[Image:Audio_decomposition.png]]

The audio subsystem has to take into account some requirements coming from hardware characteristics which influence the design of the software subsystem:
*Audio signals can be outputed through the IHF or through wired/Bluetooth headsets
*The loudspeaker and headphones share the same audio signal
*Hardware volume control is provided for both headset and for IHF, but not for microphones.
*Microphone selection between IHF and headset is done using an analog switch, no hardware amplification control for either.

These aspects led to the following design choices:
*Audio signal routing is done using headphone and IHF amplifier volume control
*Microphone AGC is implemented
*Master volume control will correspond to
**IHF amplifier volume control when IHF is in use
**Headphone amplifier volume control when headset/headphone is in use
**BT headset/headphone volume setting when BT is in use

In addition, Audio Post-Processor is always enabled. It needs different tunings for IHF, wired headset (assumed to be HS-48 like), BT headset and generic headphone.

Alarm is played through the loudspeaker even if headphones are connected and can’t be mixed to other sounds. This is a UI requirement.

===Audio Codecs===
Most of the audio encoders and decoders are wrapped under the OpenMAX IL interface [OMAX], which abstracts the codec specific implementation (which in general can run on ARM or DSP). Unless a different solution is needed (due e.g. to sourcing problems, performance requirements or to fulfill some specific use cases) all the audio codecs will be running on the ARM side to simplify the audio architecture and to avoid the additional latency and load over the data path due to the routing of the audio data first to DSP and then back to ARM.

===ALSA library===
ALSA (Advanced Linux Sound Architecture) is a standard audio interface for Linux applications.

{|cellspacing="0" border="1" width="70%"
|'''Name'''||ALSA library
|-
|'''Purpose'''||It can be used by conventional Linux applications to play/record raw audio
|-
|'''Responsibilities'''||Provides a transparent access to audio driver
|-
|'''License'''||GPL/LGPL
|-
|'''Packages'''||alsa-lib, alsa-plugins, alsa-utils
|}

====Public interface provided by ALSA library====
{|cellspacing="0" border="1" width="70%"
|'''Interface name'''||'''Description'''
|-
|ALSA||Interface for Conventional Linux Audio Applications.
|}

===PulseAudio===
PulseAudio is a networked sound server, similar in theory to the Enlightened Sound Daemon (ESound). PulseAudio is however much more advanced and has numerous features:
*Software mixing of multiple audio streams, bypassing any restrictions the hardware has.
*Sample rate conversion of audio streams
*Network transparency, allowing an application to play back or record audio on a different machine than the one it is running on.
*Sound API abstraction, alleviating the need for multiple backends in applications to handle the wide diversity of sound systems out there.
*Generic hardware abstraction, giving the possibility of doing things like individual volumes per application.
*PulseAudio comes with many plugin modules.

{|cellspacing="0" border="1" width="70%"
|'''Name'''||'''PulseAudio'''
|-
|'''Purpose'''||It can be used by conventional Linux applications to play/record raw audio
|-
|'''Responsibilities'''||Provides a transparent access to audio driver and performs audio mixing and sample rate conversion.
|-
|'''License'''||GPL/LGPL
|-
|'''Packages'''||pulseaudio
|}

====Public interface provided by PulseAudio====
{|cellspacing="0" border="1" width="70%"
|'''Interface name'''||'''Description'''
|-
|ESound||ESD (Enlightened Sound Daemon) is a standard audio interface for Linux applications Note: the interface is provided for backwards compatibility only. No new software should use it anymore.
|-
|PulseAudio||Internal Interface for Audio Applications (e.g. used by the GStreamer Pulse Sink and Source)
|}

===EAP and AEP===
The EAP (Entertainment Audio Platform) package is used for audio post-processing (music DRC and stereo widening).

AEP (Audio Enhancements Package) is a full duplex speech audio enhancement package including echo cancellation, background noise suppression, DRC, AGC, etc.
Both EAP and AEP are implemented as a PulseAudio module.

===FMTX Middleware===
FMTX middleware provides a daemon for controlling the FM Transmitter. The daemon listens to commands from clients via dbus system interface. The frequency of the transmitter is controlled via Video4Linux2 interface. Note that the transmitter must be unmuted before changing frequency. This is because the device is muted by default and when the device is muted, it's not powered. Other settings are controlled by sysfs files in directory /sys/bus/i2c/devices/2-0063/.

The wire of the headset acts as an antenna, boosting fmtx transmission power over allowed limits. Therefore the daemon is monitoring plugged devices and powers the transmitter down, if the headset is not connected.
GConf: system/fmtx/:
*Bool enabled
*Int frequency

===Audio/ Video Synchronization===
The audio / video synchronization is done using the standard mechanisms built-in to the GStreamer framework. This requires that a clock source is available. The clock must be such that it stays in sync with the audio HW. Like in normal Linux desktops, this is achieved by exporting the interrupts from the audio chip through ALSA and corresponding GStreamer element.

==Notification subsystem==
MMF delivers parts of the notification mechanism. The subsytem is illustrated below:

[[Image:Notification_decomposition.png]]

===Notification Plugins===
Two notification plugins are provided,
*Sound notification plugin: Plays events and notification sounds
*Vibra notification plugin: Emits bursts of vibration and controls the vibration hw.

===Input Event Sounds===
The input event sounds module is using the Xserver xtest (http://www.xfree86.org/current/xtestlib.pdf) extension to produce input even feedback via libcanberra. The input-sound module is started with the XSession as a separate process.

==Metadata Subsystem==
The multimedia framework supports the search engine when indexing media files. The subsystem is illustrated below:

[[Image:Metadata_decomposition.png]]

===Decodebin2/TagreadBin===
The desktop search (Tracker) can use high level GStreamer components (decodebin2/tagreadbin) to gather metadata from all supported media files. Tagreadbin can provide better performance than playbin2 by avoiding to plug decoders and utilize special codepath in parsers and demuxer for getting only metadata.

==Policy Subsystem==
It is neither user friendly nor always possible to run several multimedia use cases at the same time. To provide a predictable and stable behavior, multimedia components interact with a system wide policy component to keep concurrent multimedia use cases under control. The subsystem is illustrated below. The policy engine is based on the OHM framework. It is dynamically configurable with scripting and a prolog based rule database.

[[Image:Policy_decomposition.png]]

===libplayback===
libplayback is a client API that allows an application to declare its playback state. The library uses D-Bus to talk to a central component that manages the states. Media applications can use the API to synchronize their playback state.

{|cellspacing="0" border="1" width="70%"
|'''Name'''||'''libplayback'''
|-
|'''Purpose'''||It can be used by media application to synchronize their playback state.
|-
|'''Responsibilities'''||Provides an interface for media playback management
|-
|'''License'''||Nokia
|-
|'''Packages'''||libplayback
|}

'''Public interface provided by libplayback'''
{|cellspacing="0" border="1" width="70%"
|'''Interface name'''||'''Description'''
|-
|DBUS API||Interface for requesting/ getting a playback state.
|}

===OHM Ng===
OHM Ng is a extension on top of OHM (the open harware manager project). OMH Ng provides the policy management for the system. In Fremantle, system policy only deals with multimedia resources.

{|cellspacing="0" border="1" width="70%"
|'''Name'''||'''OHM Ng'''
|-
|'''Purpose'''||System policy management
|-
|'''Responsibilities'''||*Receives policy requests *Evaluates policy rules *Notify applications of policy decisions *Use available enforcement points
|-
|'''License'''||Nokia
|-
|'''Packages'''||ohm, ohm-plugins-core0, ohm-dev, ohm-dbg (includes some enforcement point plugins and libraries)
|}

===PulseAudio Policy Enforcement Point===
PulseAudio plugin to manage volume levels, re-route streams and eventually forcefully shutdown streams.

{|cellspacing="0" border="1" width="70%"
|'''Name'''||'''PulseAudio PEP'''
|-
|'''Purpose'''||Monitors headsets/ headphones connection status
|-
|'''Responsibilities'''||*Sets the correct audio routing according to the headsets / headphones connection status * Sets the volume levels at device start-up and ensures it is put to a safe level when headphones are used *Sets the correct tuning to Audio Post Processing and Audio Enhancement Package
License Nokia
|-
|'''Packages'''||ohm, ohm-plugins-core0, ohm-dev, ohm-dbg (includes some enforcement point plugins and libraries)
|}

Documentation/Maemo 5 Developer Guide/Architecture/Changes

Maemo — Thu, 03 Sep 2009 14:14:48 GMT

Maemo: /* Multimedia */

The Maemo 5 platform software is based on the Debian GNU/Linux distribution. While Debian provides a significant amount of our current code base, it also defines policies for build process, packaging, file system hierarchy and other processes.
The intention is to follow current Debian code and processes as closely as possible, and deviate only when it is required due to technical or legal reasons. Differences between Debian and our policies and practices are documented in [Policy].

=Architectural changes since Maemo 4=

*OMAP3 based application processor
*USB flashing and charging
*Hardware sensors such as accelerometer and proximity
*Portrait mode
*Upstart based boot scripts
*OpenGL ES 2.0 Graphics acceleration
*IVA 2.2 Video Acceleration

==Connectivity==
*BlueZ bluetooth stack updated to Bluez 4.x
*New Bluetooth chip driver introduced which supports BT2.1 configuration, which implies that mandatory BT2.1 features are added to the kernel and userspace BlueZ stack.
*WLAN architecture is changed to use the Linux mac80211 framework [mac80211], which means that the closed source WLAN UMAC component in the kernel is removed and the new WLAN kernel implementation is fully open source.

==Multimedia==
* Clean split of decoders/sinks and encoders/sources
**Audio
***ARM optimised audio codecs
***Unmodified pulse/alsa /sink/source plugins
**Video
***DSP optimised video codecs (some via openmax)

*PulseAudio
**Audio routing and policy
**Audio pre- & post processing
*Camera-bin
**High level api for still-image and video capture
*New GStreamer plugin introduced that wraps openmax-il components under the gstreamer API
*Speex introduced
*esound replaced by libcanberra
*Upgraded multimedia framework with technology novelties such as TV-out, A2DP stereo Headsets, FM-TX and expanded codec support: H.264, Mpeg-4 ASp (Xvid), WMA10.

==UI framework==
*Removal of left side Task Navigator and plugins.
*Separate processes for status bar, home and desktop.
*hildon-desktop process implements window management, task launcher and task switcher. The task launcher is a menu with application icons.
*hildon-home process implements notification manager, desktop background and graphical widgets.
*hildon-status-menu process implements the status menu and status area.
*Removal of stylus keyboard
*Clutter introduced to access the hardware accelerated OpenGL graphics functionality. It is assumed that we have only one OpenGL drawing context and thus a single process running in the system is using clutter at a time. This process is hildon-desktop.
*UI style changes (navigation logic in applications, visual style of dialogs, menus etc)

==RTCOM==
*Farsight API break: Farsight upgraded/rewritten as Farsight2
*Mission control:
*Logger API: rtcom-eventlogger introduced whose purpose is to serve as a general framework for storing and accessing a persistent log.
*libtelepathy replaced by telepathy-glib
*libgalago and galago-daemon dropped

==Location Framework==
*Deprecated low level GPS libraries removed such as libgpsbt, libgpsmgr, gpsd daemon.
*gpsd replaced by liblocation API library and a set of on-request daemon processes for different location methods (Eg: gpypsy-daemon for bluetooth GPS, location daemon for integrated GPS and network based methods)

==Calendar Backend==
calendar-backend is a new component that provides a C++ calendar API for external applications. It interacts with SQlite database, implements the iCal RFC to store the calendar
entries and handles the database transactions.

==Media Application Framework==
The Media Application Framework (MAFW) provides an open, flexible and extensible layer that eases the development of multimedia applications for the Maemo platform. It is a complement to the Multimedia framework that has been heavily improved in Fremantle. MAFW provides:

An extendable, pluggable framework interface, which allows to develop new plugins that provide integration with new multimedia services or rendering engines, that can be seamlessly integrated in all MAFW based applications.
Easy to use APIs that speed up application developing, providing support for playback control, discovery and browsing of multimedia resources and playlist manipulation.
Independence of the technology. Since MAFW is a plugin based framework, it is not tied to a particular multimedia technology (GStreamer,MPlayer, Tracker). Plugin developers have freedom to choose the technologies they want to use in their plugins, and application developers do not need to know about them.

Documentation/Maemo 5 Developer Guide/Application Development/LibOSSO library

Maemo — Wed, 02 Sep 2009 14:05:09 GMT

Maemo: Created page with '= Overview = LibOSSO is the basic library, containing required and helpful functions for Maemo applications. The full API documentation of LibOSSO is available in Doxygen format…'

= Overview =

LibOSSO is the basic library, containing required and helpful functions for Maemo applications. The full API documentation of LibOSSO is available in Doxygen format.

= Maemo initialization =

All Maemo applications must be initialized correctly, or they do not work as expected. One symptom of missing initialization is that application starts from Task Navigator, but closes automatically after few seconds.

Initializing application is performed with <code>osso_initialize()</code> function. With this function, the application connects to D-BUS session bus and system bus. <code>osso_initialize()</code> function should only be called once in the application, and the structure of type osso_context_t type that is returned should be stored for later use. First parameter of the function is the application D-BUS name, used also in application D-BUS service file. Second parameter is the application version as a string. Third is the activation type, with TRUE the library assumes that the application binary has been launched by the D-BUS daemon, and thus connects to the D-BUS activation bus. Fourth parameter is the GLib main-loop context to connect to, NULL should be used for the default context. 

 ''osso_context_t * osso_initialize(const gchar *application, const gchar* version, gboolean activation, GMainContext *context)'' When the application is closing, osso_deinitialize function should be called to close the message bus connection and free all memory allocated by the library. ''void osso_deinitialize(osso_context_t *osso)'' 

Below is an example ([https://garage.maemo.org/svn/maemoexamples/trunk/maemo-examples/example_libosso.c example_libosso.c]) of this; if the initialization does not succeed, the function returns NULL.

<tt>'''<nowiki>#define</nowiki>''' OSSO_EXAMPLE_NAME "example_libosso"
'''<nowiki>#define</nowiki>''' OSSO_EXAMPLE_SERVICE "org.maemo."OSSO_EXAMPLE_NAME
''/* ... */''
osso_context_t <nowiki>*</nowiki>osso_context<nowiki>;</nowiki>
''/* ... */''
''/* Initialize maemo application */''
osso_context <nowiki>=</nowiki> '''osso_initialize'''(OSSO_EXAMPLE_SERVICE, "0.0.1", TRUE, NULL);
''/* Check that initialization was ok */''
'''if''' (osso_context <nowiki>==</nowiki> NULL) {
'''return''' OSSO_ERROR<nowiki>;</nowiki>
}
''/* ... */''
''/* Deinitialize OSSO */''
'''osso_deinitialize'''(osso_context);
</tt>

= Remote process messages =

System wide messages in Maemo platform are handled with D-BUS system messaging, which is a Remote Process Communication (RPC) method. LibOSSO has own wrappers to normal D-BUS functions to make usage simpler and to maintain backward compatibility. By using D-BUS, applications can send messages from one process to another.

Callback function receiving the messages can be as follows ([https://garage.maemo.org/svn/maemoexamples/trunk/maemo-examples/example_libosso.c example_libosso.c]), where AppData structure contains the initialized osso_context:

<tt>'''<nowiki>#include</nowiki>''' <hildon/hildon-program.h>
'''<nowiki>#include</nowiki>''' <hildon/hildon-banner.h>
'''<nowiki>#include</nowiki>''' <gtk/gtk.h>
'''<nowiki>#include</nowiki>''' <libosso.h>
'''<nowiki>#define</nowiki>''' OSSO_EXAMPLE_NAME "example_libosso"
'''<nowiki>#define</nowiki>''' OSSO_EXAMPLE_SERVICE "org.maemo."OSSO_EXAMPLE_NAME
'''<nowiki>#define</nowiki>''' OSSO_EXAMPLE_OBJECT "/org/maemo/"OSSO_EXAMPLE_NAME
'''<nowiki>#define</nowiki>''' OSSO_EXAMPLE_IFACE "org.maemo."OSSO_EXAMPLE_NAME
''/* ... */''
''/* Application UI data struct */''
'''typedef''' '''struct''' _AppData AppData<nowiki>;</nowiki>
'''struct''' _AppData {
HildonProgram <nowiki>*</nowiki>program<nowiki>;</nowiki>
HildonWindow <nowiki>*</nowiki>window<nowiki>;</nowiki>
osso_context_t <nowiki>*</nowiki>osso_context<nowiki>;</nowiki>
}<nowiki>;</nowiki>
''/* ... */''
''/* Callback for normal D-BUS messages */''
gint '''dbus_req_handler'''('''const''' gchar <nowiki>*</nowiki> interface, '''const''' gchar <nowiki>*</nowiki> method,
GArray <nowiki>*</nowiki> arguments, gpointer data,
osso_rpc_t <nowiki>*</nowiki> retval)
{
AppData <nowiki>*</nowiki>appdata<nowiki>;</nowiki>
appdata <nowiki>=</nowiki> (AppData <nowiki>*)</nowiki> data<nowiki>;</nowiki>
'''osso_system_note_infoprint'''(appdata->osso_context, method, retval);
'''osso_rpc_free_val'''(retval);
'''return''' OSSO_OK<nowiki>;</nowiki>
}
</tt>

To attach this callback function to receive all the normal D-BUS messages to the application, use the osso_rpc_set_default_cb_f function as follows:

<tt>int '''main'''(int argc, char <nowiki>*</nowiki>argv[])
{
osso_return_t result<nowiki>;</nowiki>

''/* ... */''
''/* Add handler for session bus D-BUS messages */''
result <nowiki>=</nowiki> '''osso_rpc_set_cb_f'''(appdata->osso_context,
OSSO_EXAMPLE_SERVICE,
OSSO_EXAMPLE_OBJECT,
OSSO_EXAMPLE_IFACE,
dbus_req_handler, appdata);

'''if''' (result <nowiki>!=</nowiki> OSSO_OK) {
'''g_print'''("Error setting D-BUS callback (%d)\n", result);
'''return''' OSSO_ERROR<nowiki>;</nowiki>
}
''/* ... */''

''/* Deinitialize OSSO */''
'''osso_deinitialize'''(osso_context);
}
</tt>

Now the application is ready to receive D-BUS messages. Whenever it receives one, the dbus_req_handler function is called to process the message. Another test application ([https://garage.maemo.org/svn/maemoexamples/trunk/maemo-examples/example_message.c example_message.c]<nowiki>), can send the ``HelloWorld'' that this application was designed to handle, as follows: </nowiki>

<tt>''/* ... */''
'''<nowiki>#define</nowiki>''' OSSO_EXAMPLE_NAME "example_libosso"
'''<nowiki>#define</nowiki>''' OSSO_EXAMPLE_SERVICE "org.maemo."OSSO_EXAMPLE_NAME
'''<nowiki>#define</nowiki>''' OSSO_EXAMPLE_OBJECT "/org/maemo/"OSSO_EXAMPLE_NAME
'''<nowiki>#define</nowiki>''' OSSO_EXAMPLE_IFACE "org.maemo."OSSO_EXAMPLE_NAME
'''<nowiki>#define</nowiki>''' OSSO_EXAMPLE_MESSAGE "HelloWorld"
''/* ... */''
ret <nowiki>=</nowiki> '''osso_rpc_run'''(osso_context,
OSSO_EXAMPLE_SERVICE,
OSSO_EXAMPLE_OBJECT,
OSSO_EXAMPLE_IFACE,
OSSO_EXAMPLE_MESSAGE, &retval, DBUS_TYPE_INVALID);
''/* ... */''</tt>

<nowiki> When example_libosso_test is started, it sends an ``example_message'' D-BUS message to org.maemo.example_libosso service, attached to the example_libosso application (See more about D-BUS service files from an earlier section). Now when example_libosso receives the message, it shows a banner. </nowiki>

One nice thing about D-BUS is that the receiving application does not even need to be started: D-BUS can automatically start the application based on its service file, and then pass the message to it!

=Hardware state messages =

<nowiki> Maemo applications can connect to listen the system D-BUS messages, like ``battery low'' and ``shutdown''. When these messages are received, the application may want to ask the user to save files that are open, or react however wanted. </nowiki>

A callback function is defined like below, taking <code>osso_hw_state_t</code> and gpointer as parameters. The changed state can be gotten from state variable ([https://garage.maemo.org/svn/maemoexamples/trunk/maemo-examples/example_libosso.c <code>example_libosso.c</code>]).

<tt>''/* Callback for hardware D-BUS events */''
void '''hw_event_handler'''(osso_hw_state_t <nowiki>*</nowiki>state, gpointer data)
{
AppData <nowiki>*</nowiki>appdata<nowiki>;</nowiki>
appdata <nowiki>=</nowiki> (AppData <nowiki>*)</nowiki> data<nowiki>;</nowiki>
'''if''' (state->shutdown_ind)
{
'''hildon_banner_show_information'''('''GTK_WIDGET'''(appdata->window), NULL,
"Shutdown event!");
}
'''if''' (state->memory_low_ind)
{
'''hildon_banner_show_information'''('''GTK_WIDGET'''(appdata->window), NULL,
"Memory low event!");
}
'''if''' (state->save_unsaved_data_ind)
{
'''hildon_banner_show_information'''('''GTK_WIDGET'''(appdata->window), NULL,
"Must save unsaved data event!");
}
'''if''' (state->system_inactivity_ind)
{
'''hildon_banner_show_information'''('''GTK_WIDGET'''(appdata->window), NULL,
"Minimize application inactivity event!");
}
}</tt>

To attach this handler, e.g. in application <code>main()</code>, use <code>osso_hw_set_event_cb()</code>.

<tt> ''/* ... */''

''/* Add handler for hardware D-BUS messages */''
result <nowiki>=</nowiki> '''osso_hw_set_event_cb'''( appdata->osso_context,
NULL, hw_event_handler, (gpointer) appdata );

'''if''' (result <nowiki>!=</nowiki> OSSO_OK)
{
'''g_print'''("Error setting HW state callback (%d)\n", result);
'''return''' OSSO_ERROR<nowiki>;</nowiki>
}

''/* ... */''</tt>

'''N.B.''' These hardware events are not sent to the SDK, so testing them is only possible in Maemo device.

= System Exit message =

A system message is sent when applications are required to close themselves. Its callback is: ([https://garage.maemo.org/svn/maemoexamples/trunk/maemo-examples/example_libosso.c example_libosso.c]):

<tt>''/* Callback for exit D-BUS event */''
void '''exit_event_handler'''(gboolean die_now, gpointer data)
{
AppData <nowiki>*</nowiki>appdata<nowiki>;</nowiki>
appdata <nowiki>=</nowiki> (AppData <nowiki>*)</nowiki> data<nowiki>;</nowiki>
'''g_print'''("exit_event_handler called\n");
''/* Do whatever application needs to do before exiting */''
'''hildon_banner_show_information'''('''GTK_WIDGET'''(appdata->window), NULL,
"Exiting...");
}</tt>

The callback is set (e.g. in application main) as follows.

<tt>int '''main'''( int argc, char<nowiki>*</nowiki> argv[] )
{
''/* ... */''
''/* Add handler for Exit D-BUS messages */''
result <nowiki>=</nowiki> '''osso_application_set_exit_cb'''(appdata->osso_context,
exit_event_handler,
(gpointer) appdata);
'''if''' (result <nowiki>!=</nowiki> OSSO_OK) {
'''g_print'''("Error setting exit callback (%d)\n", result);
'''return''' OSSO_ERROR<nowiki>;</nowiki>
}
''/* ... */''
}</tt>

Now whenever the system needs to close an application for any reason, the close is performed gracefully.

= Application state saving and auto save =

State saving is a special feature of the Maemo platform. It means that applications save their running state from RAM to permanent memory, such as flash memory, and then end the running application process. This state saving happens when switching out from the application and the device memory is running low. When the user then returns to a backgrounded application, the application restarts, the application state is read from flash memory, and the user does not even know that the application was not running all the time.

Auto saving is an addition to state saving for editor-like applications containing user data. This data/document is automatically saved at the same time with state save. The main difference is that the application state is usually just a small amount of variables describing the state where the application was, whereas the auto-saved file can be any file the user was editing. Auto saving guarantees that user files are not lost when e.g. the battery runs out.

Information on how to implement state saving can be found in LibOSSO API document.

Documentation/Maemo 5 Developer Guide/Application Development/MIME type mapping

Maemo — Wed, 02 Sep 2009 14:01:57 GMT

Maemo: Created page with '= MIME types mapping = MIME types mapping specifies for the platform which application should handle a given MIME type. A mapping has to be defined in the desktop file of the ap…'

= MIME types mapping =

MIME types mapping specifies for the platform which application should handle a given MIME type. A mapping has to be defined in the desktop file of the application by adding to it the MimeType field.

An [https://garage.maemo.org/svn/maemoexamples/trunk/maemo-examples/example_libosso.desktop example_libosso.desktop] file for the application looks like the following:

<code>[Desktop Entry]
Encoding=UTF-8
Version=1.0
Type=Application
Name=Example libOSSO
Exec=/usr/bin/example_libosso
X-Osso-Service=org.maemo.example_libosso
Icon=qgn_list_gene_default_app
MimeType=application/x-example;</code>

<nowiki> The last line is the most important one, and specifies that this application can handle the MIME type ``application/x-example''. </nowiki>

=New MIME type with OSSO category extension =

If the application is introducing a new MIME type to the system, it is necessary to provide the mime-info XML (see more at http://standards.freedesktop.org/shared-mime-info-spec/) that defines it, in this case an example-mime.xml file for the application looks as follows:

<tt>'''<?xml''' version<nowiki>=</nowiki>"1.0" encoding<nowiki>=</nowiki>"UTF-8"'''?>'''
'''<mime-info''' xmlns<nowiki>=</nowiki>"http://www.freedesktop.org/standards/shared-mime-info"
xmlns:osso<nowiki>=</nowiki>"http://nokia.com/osso/mime-categories"'''>'''
'''<mime-type''' type<nowiki>=</nowiki>"application/x-example"'''>'''
'''<comment>'''Example application file'''</comment>'''
'''<osso:category''' name<nowiki>=</nowiki>"images"'''/>'''
'''<magic''' priority<nowiki>=</nowiki>"50"'''>'''
'''<match''' type<nowiki>=</nowiki>"string" value<nowiki>=</nowiki>"FOO" offset<nowiki>=</nowiki>"0"'''/>'''
'''</magic>'''
'''<glob''' pattern<nowiki>=</nowiki>"*.foo"'''/>'''
'''</mime-type>'''
'''</mime-info>'''
</tt>

<nowiki> This entry maps one extension and a ``magic'' string to the ``application/x-example'' MIME type. </nowiki>

'''N.B.''' The glob pattern should be given in lowercase.

= What is OSSO category =

The platform has a notion of file categories for the user's data files. The available categories are:

* Bookmarks
* Contacts
* Documents
* Emails
* Images
* Audio
* Video
* Other

A mapping is set up between categories and MIME types, so that the MIME type of a file determines its category. The MIME type setup is handled by the shared-mime-info infrastructure, and the category information is added to that same framework.

Adding a mapping between a category and a number of MIME types is performed much like adding or editing the supported MIME types in the system.

Each application or library that adds a category mapping should add a file in

/usr/share/mime/packages/

The file format is the same XML format used for MIME types, with an added tag `` 8.7.3 Updating platform databases

To introduce the newly defined MIME type(s) to the platform, do the following:

# Copy the mime-information XML under /usr/share/mime/packages:

[sbox-FREMANTLE_X86: ~] > cp example-mime.xml /usr/share/mime/packages

# Update the MIME and desktop database:

[sbox-FREMANTLE_X86: ~] > update-mime-database /usr/share/mime
[sbox-FREMANTLE_X86: ~] > update-desktop-database /usr/share/applications

# Update the OSSO category database:

[sbox-FREMANTLE_X86: ~] > hildon-update-category-database /usr/share/mime

To remove the MIME from the platform, delete the XML file in /usr/share/mime/packages/ and update the databases as above.

= Registering MIME type with package =

Because most of the applications are installed on the platform via pre-compiled packages, the MIME type registration has to be performed as well.

The steps are similar to the ones shown above.

To install the MIME information XML under /usr/share/mime/packages, edit the package rules and install the files. In this case it looks as follows:

* in the '''rules''' file under install section, add the following lines:
<tt>mkdir -p $(CURDIR)/debian/tmp/usr/share/mime/packages
cp $(CURDIR)/example-mime.xml $(CURDIR)/debian/tmp/usr/share/mime/packages</tt>
* and in .install we need to add
<tt>usr/share/mime/packages/example-mime.xml</tt>

This way, it can be assured that the mime information XML is being installed under /usr/share/mime/packages.

Add the following lines to both the postinst and postrm files of the package:

<tt>'''if''' [ -x /usr/bin/update-mime-database ]; '''then'''
update-mime-database /usr/share/mime
'''fi'''
'''if''' [ -x /usr/bin/update-desktop-database ]; '''then'''
update-desktop-database /usr/share/applications
'''fi'''
'''if''' [ -x /usr/bin/hildon-update-category-database ]; '''then'''
hildon-update-category-database /usr/share/mime
'''fi'''</tt>

This keeps the platform mime information and OSSO category databases up-to-date.

Documentation/Maemo 5 Developer Guide/Using Data Sharing/Clipboard Usage

Maemo — Wed, 02 Sep 2009 13:35:06 GMT

Maemo: /* Overview */

=Overview=

In maemo, there is a number of clipboard enhancements to the X clipboard and Gtk+, in order to

* Support retaining the clipboard data when applications that own the clipboard exit.
* Be able to copy and paste rich text data between Gtk+ text views in different applications.
* <nowiki>Provide a generally more pleasant user experience; make it easy for application developers to gray out ``Paste'' menu items when the clipboard data format is not supported by the application. </nowiki>

This section uses the following example code:
* [https://garage.maemo.org/svn/maemoexamples/trunk/maemopad/src/ maemopad]

=GtkClipboard API changes =

<tt>gboolean '''gtk_clipboard_set_can_store''' (GtkClipboard <nowiki>*</nowiki>clipboard
GtkTargetEntry <nowiki>*</nowiki>targets,
gint n_targets);</tt>

This function sets what data targets the current clipboard owner can transfer to the clipboard manager. NULL can be passed as targets, together with 0 as n_targets to indicate that all targets can be transferred.

When the clipboard owner changes, these values are reset.

<tt>void '''gtk_clipboard_store''' (GtkClipboard <nowiki>*</nowiki>clipboard);</tt>

This function tells the clipboard to try and store the contents of the targets specified using gtk_clipboard_set_can_store. If no such call has been made, or if there is no clipboard manager around, this function is simply a no-op.

Applications can call this function when exiting, but it is called automatically, when the application is quitting, if quitting with gtk_main_quit(). If the application is not the owner of the clipboard, the function will simply be a no-op.

<nowiki> In addition, adding a convenience function for finding out if a target is supported (in order to be able to gray out ``Paste'' items, if none of the existing clipboard targets are supported) </nowiki>

<tt>gboolean '''gtk_clipboard_wait_is_target_available''' (GtkClipboard <nowiki>*</nowiki>clipboard,
GdkAtom target);</tt>

= GtkTextBuffer API changes =

In order to support rich text copy and paste, some new functions were introduced:

<tt>void
'''gtk_text_buffer_set_enable_paste_rich_text''' (GtkTextBuffer <nowiki>*</nowiki>buffer,
gboolean can_paste_rich_text);
gboolean
'''gtk_text_buffer_get_enable_paste_rich_text''' (GtkTextBuffer <nowiki>*</nowiki>buffer);</tt>

The setter function toggles, whether it should be possible to paste rich text in a text buffer.

<nowiki> To prevent applications from getting confused, when text with unexpected tags is pasted to a buffer, the notion of ``rich text format'' was added: </nowiki>

<tt>void
'''gtk_text_buffer_set_rich_text_format''' (GtkTextBuffer <nowiki>*</nowiki>buffer,
'''const''' gchar <nowiki>*</nowiki>format);
G_CONST_RETURN <nowiki>*</nowiki>
'''gtk_text_buffer_get_rich_text_format''' (GtkTextBuffer <nowiki>*</nowiki>buffer);</tt>

<nowiki> When a buffer has a certain text format, it can only paste rich text from buffers that have the same text format. If the formats differ, only plain text will be pasted. If a buffer has its format set to NULL, it means that it can paste from any format. For example, a format called ``html'' could include the tags ``bold'', ``italic'' etc. Thus, it would only be possible to paste text from buffers having the same format specified. </nowiki>

'''N.B.''' The string is just an identifier. It is up to the application developers to make sure that when specifying an application as supporting a certain format, also the tags in the buffer are specified for that format.

For further details, MaemoPad source code is a good example to study.

Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Application Preferences-Gconf

Maemo — Wed, 02 Sep 2009 12:28:17 GMT

Maemo: /* Application Preferences - GConf */

= Application Preferences - GConf=

GConf is used by the GNOME desktop environment for storing shared configuration settings for the desktop and applications. The daemon process GConfd follows the changes in the database. When a change occurs in the database, the daemon applies the new settings to the applications using them. For example, the control panel application uses GConf.

If settings are used only by a single application, Glib utility for .ini style files should be used instead. Applications should naturally have working default settings. Settings should be saved only when the user changes them.

This chapter uses the following example:
*[https://garage.maemo.org/svn/maemoexamples/trunk/support-libraries/hildon_helloworld-9.c hildon_helloworld-9.c]
*[https://garage.maemo.org/svn/maemoexamples/trunk/gconf-listener/ gconf-listener]

==GConf Basics==

GConf is a system for GNOME applications to store settings into a database system in a centralized manner. The aim of the GConf library is to provide applications a consistent view of the database access functions, as well as to provide tools for system administrators to enable them to distribute software settings in a centralized manner (across multiple computers).

The GConf "database" may consist of multiple databases (configured by the system administrator), but normally there will be at least one database engine that uses XML to store settings. This keeps the database still in a human readable form (as opposed to binary), and allows some consistency checks via schema verifications.

The interface for the client (program that uses GConf to store its settings) is always the same, irrespective of the database back-end (the client does not see this).

What makes GConf interesting, is its capability of notifying running clients that their settings have been changed by some other process than themselves. This allows for the clients to react soon (not quite real-time), and this leads to a situation where a user will change, for example, the GNOME HTTP proxy settings, and clients that are interested in that setting will get a notification (via a callback function) that the setting has changed. The clients will then read the new setting and modify their data structures to take the new setting into account.

==Using GConf ==

The GConf model consists of two parts: the GConf client library (which will be used here) and the GConf server daemon that is the guardian and reader/writer of the back-end databases. In a regular GNOME environment, the client communicates with the server either by using the Bonobo library (lightweight object IPC mechanism) or D-Bus.

As Bonobo is not used in maemo (it is quite heavy, even if lightweight), the client will communicate with the server using D-Bus. This also allows the daemon to be started on demand, when there is at least one client wanting to use that service (this is a feature of D-Bus). The communication mechanism is encapsulated by the GConf client library, and as such, will be transparent.

In order to read or write the preference database, it is necessary to decide on the key to use to access the application values. The database namespace is hierarchical, and uses the '/'-character to implement this hierarchy, starting from a root location similar to UNIX file system namespace.

Each application will use its own "directory" under '''/apps/Maemo/appname/'''. N.B. Even when the word "directory" is seen in connection to GConf, one has to be careful to distinguish '''real directories''' from '''preference namespaces''' inside the GConf namespace. The /apps/Maemo/appname/ above is in the GConf namespace, so there will not actually be a physical directory called '''/apps/''' on a system.

The keys should be named according to the platform guidelines. The current guideline is that each application should store its configuration keys under '''/apps/Maemo/appname/''', where appname is the name of the application. There is no central registry on the names in use currently, so names should be selected carefully. Key names should all be lowercase, with underscore used to separate multiple words. Also, ASCII should be used, since GConf does not support localization for key names (it does for key values, but that is not covered in this material).

GConf values are typed, which means that it is necessary to select the type for the data that the key is supposed to hold.

The following types are supported for values in GConf:

* gint (32-bit signed)
* gboolean
* gchar (ASCII/ISO 8859-1/UTF-8 C string)
* gfloat (with the limitation that the resolution is not guaranteed nor specified by GConf because of portability issues)
* a list of values of one type
* a pair of values, each having their own type (useful for storing "mapping" data)

What is missing from the above list is storing binary data (for a good reason). The type system is also fairly limited. This is on purpose, so that complex configurations (like the Apache HTTP daemon uses, or Samba) are not attempted using GConf.

There is a diagnostic and administration tool called gconftool-2 that is also available in the SDK. It can be used to set and unset keys, as well as display their current contents.

Some examples of using gconftool-2 (on the SDK):

* Displaying the contents of all keys stored under '''/apps/''' (listing cut for brevity) 

[sbox-DIABLO_X86: ~] > run-standalone.sh gconftool-2 -R /apps
/apps/osso:
/apps/osso/inputmethod:
launch_finger_kb_on_select = true
input_method_plugin = himExample_vkb
available_languages = [en_GB]
use_finger_kb = true
/apps/osso/inputmethod/hildon-im-languages:
language-0 = en_GB
current = 0
language-1 =
list = []
/apps/osso/fontconfig:
font_scaling_factor = Schema (type: `float' list_type:
'*invalid*' car_type: '*invalid*' cdr_type: '*invalid*'
locale: `C')
/apps/osso/apps:
/apps/osso/apps/controlpanel:
groups = [copa_ia_general,copa_ia_connectivity,
copa_ia_personalisation]
icon_size = false
group_ids = [general,connectivity,personalisation]
/apps/osso/osso:
/apps/osso/osso/thumbnailers:
/apps/osso/osso/thumbnailers/audio@x-mp3:
command = /usr/bin/hildon-thumb-libid3
/apps/osso/osso/thumbnailers/audio@x-m4a:
command = /usr/bin/hildon-thumb-libid3
/apps/osso/osso/thumbnailers/audio@mp3:
command = /usr/bin/hildon-thumb-libid3
/apps/osso/osso/thumbnailers/audio@x-mp2:
command = /usr/bin/hildon-thumb-libid3

* Creating and setting the value to a new key. 

[sbox-DIABLO_X86: ~] > run-standalone.sh gconftool-2 \
--set /apps/Maemo/testing/testkey --type=int 5

* Listing all keys under the namespace '''/apps/Maemo/testing'''. 

[sbox-DIABLO_X86: ~] > run-standalone.sh gconftool-2 \
-R /apps/Maemo/testing
testkey = 5

* Removing the last key will also remove the key directory. 

[sbox-DIABLO_X86: ~] > run-standalone.sh gconftool-2 \
--unset /apps/Maemo/testing/testkey
[sbox-DIABLO_X86: ~] > run-standalone.sh gconftool-2 \
-R /apps/Maemo/testing

* Removing whole key hierarchies is also possible. 

[sbox-DIABLO_X86: ~] > run-standalone.sh gconftool-2 \
--recursive-unset /apps/Maemo/testing

For more detailed information, please see [http://maemo.org/api_refs/5.0/beta/gconf2/ Gconf API documentation].

== Using GConf to read and write preferences ==

Section ''Application Settings'' [/node9.html#sec:application_settings [[Image:crossref.png|[*]]]] of chapter ''Application Development'' in Maemo Reference Manual presents a short introductory example of gconf usage. The following example is a bit more complicated.

The example is required to:

* Store the color that the user selects when the color button (in the toolbar) is used.
* Load the color preference on application startup.

Even if GConf concepts seem to be logical, it can be seen that using GConf will require one to learn some new things (e.g. the GError-object). Since the GConf client code is in its own library, the relevant compiler flags and library options need to be added again. The pkg-config package name is gconf-2.0 hildon_helloworld-9.c

<tt>''/**''
'' * hildon_helloworld-9.c''
'' *''
'' * This maemo code example is licensed under a MIT-style license,''
'' * that can be found in the file called "License" in the same''
'' * directory as this file.''
'' * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.''
'' *''
'' * We'll store the color that the user selects into a GConf''
'' * preference. In fact, we'll have three settings, one for each''
'' * channel of the color (red, green and blue).''
'' *''
'' * Look for lines with "NEW" or "MODIFIED" in them.''
'' */''

'''<nowiki>#include</nowiki>''' <stdlib.h>
'''<nowiki>#include</nowiki>''' <hildon/hildon-program.h>
'''<nowiki>#include</nowiki>''' <hildon/hildon-color-button.h>
'''<nowiki>#include</nowiki>''' <hildon/hildon-find-toolbar.h>
'''<nowiki>#include</nowiki>''' <hildon/hildon-file-chooser-dialog.h>
'''<nowiki>#include</nowiki>''' <hildon/hildon-banner.h>
'''<nowiki>#include</nowiki>''' <libgnomevfs/gnome-vfs.h>
''/* Include the prototypes for GConf client functions (NEW). */''
'''<nowiki>#include</nowiki>''' <gconf/gconf-client.h>

''/* The application name -part of the GConf namespace (NEW). */''
'''<nowiki>#define</nowiki>''' APP_NAME "hildon_hello"
''/* This will be the root "directory" for our preferences (NEW). */''
'''<nowiki>#define</nowiki>''' GC_ROOT "/apps/Maemo/" APP_NAME "/"

''/*... Listing cut for brevity ...*/''

''/**''
'' * NEW''
'' *''
'' * Utility function to store the given color into our application''
'' * preferences. We could use a list of integers as well, but we'll''
'' * settle for three separate properties; one for each of RGB''
'' * channels.''
'' *''
'' * The config keys that will be used are 'red', 'green' and 'blue'.''
'' *''
'' * NOTE:''
'' * We're doing things very non-optimally. If our application would''
'' * have multiple preference settings, and we would like to know''
'' * when someone will change them (external program, another''
'' * instance of our program, etc), we'd have to keep a reference to''
'' * the GConf client connection. Listening for changes in''
'' * preferences would also require a callback registration, but this''
'' * is covered in the "maemo Platform Development" material.''
'' */''
'''static''' void '''confStoreColor'''('''const''' GdkColor<nowiki>*</nowiki> color) {

''/* We'll store the pointer to the GConf connection here. */''
GConfClient<nowiki>*</nowiki> gcClient <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

''/* Make sure that no NULLs are passed for the color. GdkColor is''
'' not a proper GObject, so there is no GDK_IS_COLOR macro. */''
'''g_assert'''(color);

'''g_print'''("confStoreColor: invoked\n");

''/* Open a connection to gconfd-2 (via D-Bus in maemo). The GConf''
'' API doesn't say whether this function can ever return NULL or''
'' how it will behave in error conditions. */''
gcClient <nowiki>=</nowiki> '''gconf_client_get_default'''();
''/* We make sure that it's a valid GConf-client object. */''
'''g_assert'''('''GCONF_IS_CLIENT'''(gcClient));

''/* Store the values. */''
'''if''' (!'''gconf_client_set_int'''(gcClient, GC_ROOT "red", color->red,
NULL)) {
'''g_warning'''(" failed to set %s/red to %d\n", GC_ROOT, color->red);
}
'''if''' (!'''gconf_client_set_int'''(gcClient, GC_ROOT "green", color->green,
NULL)) {
'''g_warning'''(" failed to set %s/green to %d\n", GC_ROOT,
color->green);
}
'''if''' (!'''gconf_client_set_int'''(gcClient, GC_ROOT "blue", color->blue,
NULL)) {
'''g_warning'''(" failed to set %s/blue to %d\n", GC_ROOT,
color->blue);
}

''/* Release the GConf client object (with GObject-unref). */''
'''g_object_unref'''(gcClient);
gcClient <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
}

''/**''
'' * NEW''
'' *''
'' * A utility function to get an integer but also return the status''
'' * whether the requested key existed or not.''
'' *''
'' * NOTE:''
'' * It's also possible to use gconf_client_get_int(), but it's not''
'' * possible to then know whether they key existed or not, because''
'' * the function will return 0 if the key doesn't exist (and if the''
'' * value is 0, how could you tell these two conditions apart?).''
'' *''
'' * Parameters:''
'' * - GConfClient: the client object to use''
'' * - const gchar*: the key''
'' * - gint*: the address to store the integer to if the key exists''
'' *''
'' * Returns:''
'' * - TRUE: if integer has been updated with a value from GConf.''
'' * FALSE: there was no such key or it wasn't an integer.''
'' */''
'''static''' gboolean '''confGetInt'''(GConfClient<nowiki>*</nowiki> gcClient, '''const''' gchar<nowiki>*</nowiki> key,
gint<nowiki>*</nowiki> number) {

''/* This will hold the type/value pair at some point. */''
GConfValue<nowiki>*</nowiki> val <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
''/* Return flag (tells the caller whether this function wrote behind''
'' the 'number' pointer or not). */''
gboolean hasChanged <nowiki>=</nowiki> FALSE<nowiki>;</nowiki>

''/* Try to get the type/value from the GConf DB.''
'' NOTE:''
'' We're using a version of the getter that will not return any''
'' defaults (if a schema would specify one). Instead, it will''
'' return the value if one has been set (or NULL).''

'' We're not really interested in errors as this will return a NULL''
'' in case of missing keys or errors and that is quite enough for''
'' us. */''
val <nowiki>=</nowiki> '''gconf_client_get_without_default'''(gcClient, key, NULL);
'''if''' (val <nowiki>==</nowiki> NULL) {
''/* Key wasn't found, no need to touch anything. */''
'''g_warning'''("confGetInt: key %s not found\n", key);
'''return''' FALSE<nowiki>;</nowiki>
}

''/* Check whether the value stored behind the key is an integer. If''
'' it is not, we issue a warning, but return normally. */''
'''if''' (val->type <nowiki>==</nowiki> GCONF_VALUE_INT) {
''/* It's an integer, get it and store. */''
<nowiki>*</nowiki>number <nowiki>=</nowiki> '''gconf_value_get_int'''(val);
''/* Mark that we've changed the integer behind 'number'. */''
hasChanged <nowiki>=</nowiki> TRUE<nowiki>;</nowiki>
} '''else''' {
'''g_warning'''("confGetInt: key %s is not an integer\n", key);
}

''/* Free the type/value-pair. */''
'''gconf_value_free'''(val);
val <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''return''' hasChanged<nowiki>;</nowiki>
}

''/**''
'' * NEW''
'' *''
'' * Utility function to change the given color into the one that is''
'' * specified in application preferences.''
'' *''
'' * If some key is missing, that channel is left untouched. The''
'' * function also checks for proper values for the channels so that''
'' * invalid values are not accepted (guint16 range of GdkColor).''
'' *''
'' * Parameters:''
'' * - GdkColor*: the color structure to modify if changed from prefs.''
'' *''
'' * Returns:''
'' * - TRUE if the color was been changed by this routine.''
'' * FALSE if the color wasn't changed (there was an error or the''
'' * color was already exactly the same as in the preferences).''
'' */''
'''static''' gboolean '''confLoadCurrentColor'''(GdkColor<nowiki>*</nowiki> color) {

GConfClient<nowiki>*</nowiki> gcClient <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
''/* Temporary holders for the pref values. */''
gint red <nowiki>=</nowiki> -1<nowiki>;</nowiki>
gint green <nowiki>=</nowiki> -1<nowiki>;</nowiki>
gint blue <nowiki>=</nowiki> -1<nowiki>;</nowiki>
''/* Temp variable to hold whether the color has changed. */''
gboolean hasChanged <nowiki>=</nowiki> FALSE<nowiki>;</nowiki>

'''g_assert'''(color);

'''g_print'''("confLoadCurrentColor: invoked\n");

''/* Open a connection to gconfd-2 (via d-bus). */''
gcClient <nowiki>=</nowiki> '''gconf_client_get_default'''();
''/* Make sure that it's a valid GConf-client object. */''
'''g_assert'''('''GCONF_IS_CLIENT'''(gcClient));

'''if''' ('''confGetInt'''(gcClient, GC_ROOT "red", &red)) {
''/* We got the value successfully, now clamp it. */''
'''g_print'''(" got red = %d, ", red);
''/* We got a value, so let's limit it between 0 and 65535 (the''
'' legal range for guint16). We use the CLAMP macro from GLib for''
'' this. */''
red <nowiki>=</nowiki> '''CLAMP'''(red, 0, G_MAXUINT16);
'''g_print'''("after clamping = %d\n", red);
''/* Update & mark that at least this component changed. */''
color->red <nowiki>=</nowiki> (guint16)red<nowiki>;</nowiki>
hasChanged <nowiki>=</nowiki> TRUE<nowiki>;</nowiki>
}
''/* Repeat the same logic for the green component. */''
'''if''' ('''confGetInt'''(gcClient, GC_ROOT "green", &green)) {
'''g_print'''(" got green = %d, ", green);
green <nowiki>=</nowiki> '''CLAMP'''(green, 0, G_MAXUINT16);
'''g_print'''("after clamping = %d\n", green);
color->green <nowiki>=</nowiki> (guint16)green<nowiki>;</nowiki>
hasChanged <nowiki>=</nowiki> TRUE<nowiki>;</nowiki>
}
''/* Repeat the same logic for the last component (blue). */''
'''if''' ('''confGetInt'''(gcClient, GC_ROOT "blue", &blue)) {
'''g_print'''(" got blue = %d, ", blue);
blue <nowiki>=</nowiki> '''CLAMP'''(blue, 0, G_MAXUINT16);
'''g_print'''("after clamping = %d\n", blue);
color->blue <nowiki>=</nowiki> (guint16)blue<nowiki>;</nowiki>
hasChanged <nowiki>=</nowiki> TRUE<nowiki>;</nowiki>
}

''/* Release the client object (with GObject-unref). */''
'''g_object_unref'''(gcClient);
gcClient <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

''/* Return status if the color was been changed by this routine. */''
'''return''' hasChanged<nowiki>;</nowiki>
}

''/**''
'' * MODIFIED''
'' *''
'' * Invoked when the user selects a color (or will cancel the dialog).''
'' *''
'' * Will also write the color to preferences (GConf) each time the''
'' * color changes. We'll compare whether it has really changed (to''
'' * avoid writing to GConf is nothing really changed).''
'' */''
'''static''' void '''cbActionColorChanged'''(HildonColorButton<nowiki>*</nowiki> colorButton,
ApplicationState<nowiki>*</nowiki> app) {

''/* Local variables that we'll need to handle the change (NEW). */''
gboolean hasChanged <nowiki>=</nowiki> FALSE<nowiki>;</nowiki>
GdkColor newColor <nowiki>=</nowiki> {}<nowiki>;</nowiki>
GdkColor<nowiki>*</nowiki> curColor <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''g_assert'''(app <nowiki>!=</nowiki> NULL);

'''g_print'''("cbActionColorChanged invoked\n");
''/* Retrieve the new color from the color button (NEW). */''
'''hildon_color_button_get_color'''(colorButton, &newColor);
''/* Just an alias to save some typing (could also use''
'' app->currentColor) (NEW). */''
curColor <nowiki>=</nowiki> &app->currentColor<nowiki>;</nowiki>

''/* Check whether the color really changed (NEW). */''
'''if''' ((newColor.red <nowiki>!=</nowiki> curColor->red) <nowiki>||</nowiki>
(newColor.green <nowiki>!=</nowiki> curColor->green) <nowiki>||</nowiki>
(newColor.blue <nowiki>!=</nowiki> curColor->blue)) {
hasChanged <nowiki>=</nowiki> TRUE<nowiki>;</nowiki>
}
'''if''' (!hasChanged) {
'''g_print'''(" color not really changed\n");
'''return'''<nowiki>;</nowiki>
}
''/* Color really changed, store to preferences (NEW). */''
'''g_print'''(" color changed, storing into preferences.. \n");
'''confStoreColor'''(&newColor);
'''g_print'''(" done.\n");

''/* Update the changed color into the application state. */''
app->currentColor <nowiki>=</nowiki> newColor<nowiki>;</nowiki>
}

''/*... Listing cut for brevity ...*/''

''/**''
'' * MODIFIED''
'' *''
'' * The color of the color button will be loaded from the application''
'' * preferences (or keep the default if preferences have no setting).''
'' */''
'''static''' GtkWidget<nowiki>*</nowiki> '''buildToolbar'''(ApplicationState<nowiki>*</nowiki> app) {

GtkToolbar<nowiki>*</nowiki> toolbar <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
GtkToolItem<nowiki>*</nowiki> tbOpen <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
GtkToolItem<nowiki>*</nowiki> tbSave <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
GtkToolItem<nowiki>*</nowiki> tbSep <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
GtkToolItem<nowiki>*</nowiki> tbFind <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
GtkToolItem<nowiki>*</nowiki> tbColorButton <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
GtkWidget<nowiki>*</nowiki> colorButton <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''g_assert'''(app <nowiki>!=</nowiki> NULL);

tbOpen <nowiki>=</nowiki> '''gtk_tool_button_new_from_stock'''(GTK_STOCK_OPEN);
tbSave <nowiki>=</nowiki> '''gtk_tool_button_new_from_stock'''(GTK_STOCK_SAVE);
tbSep <nowiki>=</nowiki> '''gtk_separator_tool_item_new'''();
tbFind <nowiki>=</nowiki> '''gtk_tool_button_new_from_stock'''(GTK_STOCK_FIND);

tbColorButton <nowiki>=</nowiki> '''gtk_tool_item_new'''();
colorButton <nowiki>=</nowiki> '''hildon_color_button_new'''();
''/* Copy the color from the color button into the application state.''
'' This is done to detect whether the color in preferences matches''
'' the default color or not (NEW). */''
'''hildon_color_button_get_color'''('''HILDON_COLOR_BUTTON'''(colorButton),
&app->currentColor);
''/* Load preferences and change the color if necessary. */''
'''g_print'''("buildToolbar: loading color pref.\n");
'''if''' ('''confLoadCurrentColor'''(&app->currentColor)) {
'''g_print'''(" color not same as default one\n");
'''hildon_color_button_set_color'''('''HILDON_COLOR_BUTTON'''(colorButton),
&app->currentColor);
} '''else''' {
'''g_print'''(" loaded color same as default\n");
}
'''gtk_container_add'''('''GTK_CONTAINER'''(tbColorButton), colorButton);

''/*... Listing cut for brevity ...*/''

}</tt>

Since the graphical appearance of the program does not change (except that the ColorButton will display the correct initial color), a look will be taken at the stdout display of the program.

[sbox-DIABLO_X86: ~/appdev] > run-standalone.sh ./hildon_helloworld-9
buildToolbar: loading color pref.
confLoadCurrentColor: invoked
hildon_helloworld-9[19840]: GLIB WARNING ** default -
confGetInt: key /apps/Maemo/hildon_hello/red not found
hildon_helloworld-9[19840]: GLIB WARNING ** default -
confGetInt: key /apps/Maemo/hildon_hello/green not found
hildon_helloworld-9[19840]: GLIB WARNING ** default -
confGetInt: key /apps/Maemo/hildon_hello/blue not found
loaded color same as default
main: calling gtk_main
cbActionMainToolbarToggle invoked
cbActionColorChanged invoked
color changed, storing into preferences..
confStoreColor: invoked
done.
main: returned from gtk_main and exiting with success

When running the program for the first time, warnings about the missing keys can be expected (since the values were not present in GConf).

Run the program again and exit:

[sbox-DIABLO_X86: ~/appdev] > run-standalone.sh ./hildon_helloworld-9
buildToolbar: loading color pref.
confLoadCurrentColor: invoked
got red = 65535, after clamping = 65535
got green = 65535, after clamping = 65535
got blue = 0, after clamping = 0
color not same as default one
main: calling gtk_main
main: returned from gtk_main and exiting with success

The next step is to remove one key (red), and run the program again (this is to test and verify that the logic works):

[sbox-DIABLO_X86: ~/appdev] > run-standalone.sh gconftool-2 \
--unset /apps/Maemo/hildon_hello/red
[sbox-DIABLO_X86: ~/appdev] > run-standalone.sh gconftool-2 \
-R /apps/Maemo/hildon_hello
green = 65535
blue = 0
[sbox-DIABLO_X86: ~/appdev] > run-standalone.sh ./hildon_helloworld-9
buildToolbar: loading color pref.
confLoadCurrentColor: invoked
hildon_helloworld-9[19924]: GLIB WARNING ** default -
confGetInt: key /apps/Maemo/hildon_hello/red not found
got green = 65535, after clamping = 65535
got blue = 0, after clamping = 0
color not same as default one
main: calling gtk_main
main: returned from gtk_main and exiting with success

== Asynchronous GConf ==

=== Listening to changes in GConf ===

Now it is time to see how to extend GConf to be more suitable in asynchronous work, and especially when implementing services.

When the configuration needs for the service are simple, and reacting to configuration changes in "realtime" is desired, it is advisable to use GConf. Also, people tend to use GConf when they are too lazy to write their own configuration file parsers (although there is a simple one in GLib), or too lazy to write the GUI part to change the settings. This example program will simulate the first case, and react to changes in a subset of GConf configuration name space when the changes happen.

The application will be interested in two string values; one to set the device to use for communication (connection), and the other to set the communication parameters for the device (connectionparams). Since this example will be concentrating on just the change notifications, the program logic is simplified by omitting the proper set-up code in the program. This means that it is necessary to set up some values to the GConf keys prior to running the program. For this, gconftool-2 will be used, and a target has been prepared in the '''Makefile''' just for this (see section [http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/GNU_Build_System#GNU_Make_and_Makefiles GNU Make and Makefiles] if necessary): gconf-listener/Makefile

<tt>''<nowiki># Define a variable for this so that the GConf root may be changed</nowiki>''
gconf_root <nowiki>:=</nowiki> /apps/Maemo/platdev_ex

''<nowiki># ... Listing cut for brevity ...</nowiki>''

''<nowiki># This will setup the keys into default values.</nowiki>''
''<nowiki># It will first do a clear to remove any existing keys.</nowiki>''
primekeys<nowiki>:</nowiki> clearkeys
gconftool-2 -set -type string \
$(gconf_root)/connection btcomm0
gconftool-2 -set -type string \
$(gconf_root)/connectionparams 9600,8,N,1

''<nowiki># Remove all application keys</nowiki>''
clearkeys<nowiki>:</nowiki>
@gconftool-2 -recursive-unset $(gconf_root)

''<nowiki># Dump all application keys</nowiki>''
dumpkeys<nowiki>:</nowiki>
@echo Keys under $(gconf_root)<nowiki>:</nowiki>
@gconftool-2 -recursive-list $(gconf_root)
</tt>

The next step is to prepare the keyspace by running the primekeys target, and to verify that it succeeds by running the dumpkeys target:

[sbox-DIABLO_X86: ~/gconf-listener] > make primekeys
gconftool-2 --set --type string \
/apps/Maemo/platdev_ex/connection btcomm0
gconftool-2 --set --type string \
/apps/Maemo/platdev_ex/connectionparams 9600,8,N,1
[sbox-DIABLO_X86: ~/gconf-listener] > make dumpkeys
Keys under /apps/Maemo/platdev_ex:
connectionparams = 9600,8,N,1
connection = btcomm0

=== Implementing Notifications on Changes in GConf ===

The first step here is to take care of the necessary header information. The GConf namespace settings have been all implemented using cpp macros, so that one can easily change the prefix of the name space if required later on. gconf-listener/gconf-key-watch.c

<tt>'''<nowiki>#include</nowiki>''' <glib.h>
'''<nowiki>#include</nowiki>''' <gconf/gconf-client.h>
'''<nowiki>#include</nowiki>''' <string.h> ''/* strcmp */''

''/* As per maemo Coding Style and Guidelines document, we use the''
'' /apps/Maemo/ -prefix.''
'' NOTE: There is no central registry (as of this moment) that you''
'' could check that your application name doesn't collide with''
'' other application names, so caution is advised! */''
'''<nowiki>#define</nowiki>''' SERVICE_GCONF_ROOT "/apps/Maemo/platdev_ex"

''/* We define the names of the keys symbolically so that we may change''
'' them later if necessary, and so that the GConf "root directory" for''
'' our application will be automatically prefixed to the paths. */''
'''<nowiki>#define</nowiki>''' SERVICE_KEY_CONNECTION \
SERVICE_GCONF_ROOT "/connection"
'''<nowiki>#define</nowiki>''' SERVICE_KEY_CONNECTIONPARAMS \
SERVICE_GCONF_ROOT "/connectionparams"</tt>

The main starts innocently enough, by creating a GConf client object (that encapsulates the connection to the GConf daemon), and then displays the two values on output: gconf-listener/gconf-key-watch.c

<tt>int '''main''' (int argc, char<nowiki>**</nowiki> argv) {
''/* Will hold reference to the GConfClient object. */''
GConfClient<nowiki>*</nowiki> client <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
''/* Initialize this to NULL so that we'll know whether an error''
'' occurred or not (and we don't have an existing GError object''
'' anyway at this point). */''
GError<nowiki>*</nowiki> error <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
''/* This will hold a reference to the mainloop object. */''
GMainLoop<nowiki>*</nowiki> mainloop <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''g_print'''(PROGNAME ":main Starting.\n");

''/* Must be called to initialize GType system. The API reference for''
'' gconf_client_get_default() insists.''
'' NOTE: Using gconf_init() is deprecated! */''
'''g_type_init'''();

''/* Create a new mainloop structure that we'll use. Use default''
'' context (NULL) and set the 'running' flag to FALSE. */''
mainloop <nowiki>=</nowiki> '''g_main_loop_new'''(NULL, FALSE);
'''if''' (mainloop <nowiki>==</nowiki> NULL) {
'''g_error'''(PROGNAME ": Failed to create mainloop!\n");
}

''/* Create a new GConfClient object using the default settings. */''
client <nowiki>=</nowiki> '''gconf_client_get_default'''();
'''if''' (client <nowiki>==</nowiki> NULL) {
'''g_error'''(PROGNAME ": Failed to create GConfClient!\n");
}

'''g_print'''(PROGNAME ":main GType and GConfClient initialized.\n");

''/* Display the starting values for the two keys. */''
'''dispStringKey'''(client, SERVICE_KEY_CONNECTION);
'''dispStringKey'''(client, SERVICE_KEY_CONNECTIONPARAMS);</tt>

The dispStringKey utility is rather simple as well, building on the GConf material that was covered in the previous section [localhost#sec:using_gconf_to_read_write_pref 9.3.2]<nowiki>: </nowiki>gconf-listener/gconf-key-watch.c

<tt>''/**''
'' * Utility to retrieve a string key and display it.''
'' * (Just as a small refresher on the API.)''
'' */''
'''static''' void '''dispStringKey'''(GConfClient<nowiki>*</nowiki> client,
'''const''' gchar<nowiki>*</nowiki> keyname) {

''/* This will hold the string value of the key. It will be''
'' dynamically allocated for us, so we need to release it ourselves''
'' when done (before returning). */''
gchar<nowiki>*</nowiki> valueStr <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

''/* We're not interested in the errors themselves (the last''
'' parameter), but the function will return NULL if there is one,''
'' so we just end in that case. */''
valueStr <nowiki>=</nowiki> '''gconf_client_get_string'''(client, keyname, NULL);

'''if''' (valueStr <nowiki>==</nowiki> NULL) {
'''g_error'''(PROGNAME ": No string value for %s. Quitting\n", keyname);
''/* Application terminates. */''
}

'''g_print'''(PROGNAME ": Value for key '%s' is set to '%s'\n",
keyname, valueStr);

''/* Normally one would want to use the value for something beyond''
'' just displaying it, but since this code doesn't, we release the''
'' allocated value string. */''
'''g_free'''(valueStr);
}</tt>

Next, the GConf client is told to attach itself to a specific name space part that this example is going to operate with: gconf-listener/gconf-key-watch.c

<tt> ''/**''
'' * Register directory to watch for changes. This will then tell''
'' * GConf to watch for changes in this namespace, and cause the''
'' * "value-changed"-signal to be emitted. We won't be using that''
'' * mechanism, but will opt to a more modern (and potentially more''
'' * scalable solution). The directory needs to be added to the''
'' * watch list in either case.''
'' *''
'' * When adding directories, you can sometimes optimize your program''
'' * performance by asking GConfClient to preload some (or all) keys''
'' * under a specific directory. This is done via the preload_type''
'' * parameter (we use GCONF_CLIENT_PRELOAD_NONE below). Since our''
'' * program will only listen for changes, we don't want to use extra''
'' * memory to keep the keys cached.''
'' *''
'' * Parameters:''
'' * - client: GConf-client object''
'' * - SERVICEPATH: the name of the GConf namespace to follow''
'' * - GCONF_CLIENT_PRELOAD_NONE: do not preload any of contents''
'' * - error: where to store the pointer to allocated GError on''
'' * errors.''
'' */''
'''gconf_client_add_dir'''(client,
SERVICE_GCONF_ROOT,
GCONF_CLIENT_PRELOAD_NONE,
&error);

'''if''' (error <nowiki>!=</nowiki> NULL) {
'''g_error'''(PROGNAME ": Failed to add a watch to GCClient: %s\n",
error->message);
''/* Normally we'd also release the allocated GError, but since''
'' this program will terminate on g_error, we won't do that.''
'' Hence the next line is commented. */''
''/* g_error_free(error); */''

''/* When you want to release the error if it has been allocated,''
'' or just continue if not, use g_clear_error(&error); */''
}

'''g_print'''(PROGNAME ":main Added " SERVICE_GCONF_ROOT ".\n");</tt>

Proceeding with the callback function registration, we have: gconf-listener/gconf-key-watch.c

<tt> ''/* Register our interest (in the form of a callback function) for''
'' any changes under the namespace that we just added.''

'' Parameters:''
'' - client: GConfClient object.''
'' - SERVICEPATH: namespace under which we can get notified for''
'' changes.''
'' - gconf_notify_func: callback that will be called on changes.''
'' - NULL: user-data pointer (not used here).''
'' - NULL: function to call on user-data when notify is removed or''
'' GConfClient destroyed. NULL for none (since we don't''
'' have user-data anyway).''
'' - error: return location for an allocated GError.''

'' Returns:''
'' guint: an ID for this notification so that we could remove it''
'' later with gconf_client_notify_remove(). We're not going''
'' to use it so we don't store it anywhere. */''
'''gconf_client_notify_add'''(client, SERVICE_GCONF_ROOT,
keyChangeCallback, NULL, NULL, &error);
'''if''' (error <nowiki>!=</nowiki> NULL) {
'''g_error'''(PROGNAME ": Failed to add register the callback: %s\n",
error->message);
''/* Program terminates. */''
}

'''g_print'''(PROGNAME ":main CB registered & starting main loop\n");</tt>

When dealing with regular desktop software, one could use multiple callback functions; one for each key to track. However, this would require implementing multiple callback functions, and this runs a risk of enlarging the size of the code. For this reason, the example code uses one callback function, which will internally multiplex between the two keys (by using strcmp): gconf-listener/gconf-key-watch.c

<tt>''/**''
'' * Callback called when a key in watched directory changes.''
'' * Prototype for the callback must be compatible with''
'' * GConfClientNotifyFunc (for ref).''
'' *''
'' * It will find out which key changed (using strcmp, since the same''
'' * callback is used to track both keys) and the display the new value''
'' * of the key.''
'' *''
'' * The changed key/value pair will be communicated in the entry''
'' * parameter. userData will be NULL (can be set on notify_add [in''
'' * main]). Normally the application state would be carried within the''
'' * userData parameter, so that this callback could then modify the''
'' * view based on the change. Since this program does not have a state,''
'' * there is little that we can do within the function (it will abort''
'' * the program on errors though).''
'' */''
'''static''' void '''keyChangeCallback'''(GConfClient<nowiki>*</nowiki> client,
guint cnxn_id,
GConfEntry<nowiki>*</nowiki> entry,
gpointer userData) {

''/* This will hold the pointer to the value. */''
'''const''' GConfValue<nowiki>*</nowiki> value <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
''/* This will hold a pointer to the name of the key that changed. */''
'''const''' gchar<nowiki>*</nowiki> keyname <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
''/* This will hold a dynamically allocated human-readable''
'' representation of the changed value. */''
gchar<nowiki>*</nowiki> strValue <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''g_print'''(PROGNAME ": keyChangeCallback invoked.\n");

''/* Get a pointer to the key (this is not a copy). */''
keyname <nowiki>=</nowiki> '''gconf_entry_get_key'''(entry);

''/* It will be quite fatal if after change we cannot retrieve even''
'' the name for the gconf entry, so we error out here. */''
'''if''' (keyname <nowiki>==</nowiki> NULL) {
'''g_error'''(PROGNAME ": Couldn't get the key name!\n");
''/* Application terminates. */''
}

''/* Get a pointer to the value from changed entry. */''
value <nowiki>=</nowiki> '''gconf_entry_get_value'''(entry);

''/* If we get a NULL as the value, it means that the value either has''
'' not been set, or is at default. As a precaution we assume that''
'' this cannot ever happen, and will abort if it does.''
'' NOTE: A real program should be more resilient in this case, but''
'' the problem is: what is the correct action in this case?''
'' This is not always simple to decide.''
'' NOTE: You can trip this assert with 'make primekeys', since that''
'' will first remove all the keys (which causes the CB to''
'' be invoked, and abort here). */''
'''g_assert'''(value <nowiki>!=</nowiki> NULL);

''/* Check that it looks like a valid type for the value. */''
'''if''' (!'''GCONF_VALUE_TYPE_VALID'''(value->type)) {
'''g_error'''(PROGNAME ": Invalid type for gconfvalue!\n");
}

''/* Create a human readable representation of the value. Since this''
'' will be a new string created just for us, we'll need to be''
'' careful and free it later. */''
strValue <nowiki>=</nowiki> '''gconf_value_to_string'''(value);

''/* Print out a message (depending on which of the tracked keys''
'' change. */''
'''if''' ('''strcmp'''(keyname, SERVICE_KEY_CONNECTION) <nowiki>==</nowiki> 0) {
'''g_print'''(PROGNAME ": Connection type setting changed: [%s]\n",
strValue);
} '''else''' '''if''' ('''strcmp'''(keyname, SERVICE_KEY_CONNECTIONPARAMS) <nowiki>==</nowiki> 0) {
'''g_print'''(PROGNAME ": Connection params setting changed: [%s]\n",
strValue);
} '''else''' {
'''g_print'''(PROGNAME ":Unknown key: %s (value: [%s])\n", keyname,
strValue);
}

''/* Free the string representation of the value. */''
'''g_free'''(strValue);

'''g_print'''(PROGNAME ": keyChangeCallback done.\n");
}</tt>

The complications in the above code rise from the fact that GConf communicates values using a GValue structure, which can carry values of any simple type. Since GConf (or the user for that matter) cannot be completely trusted to return the correct type for the value, it is necessary to be extra careful, and not assume that it will always be a string. GConf also supports "default" values, which are communicated to the application using NULLs, so it is also necessary to guard against that. Especially since the application does not provide a schema for the configuration space that would contain the default values.

The next step is to build and test the program. The program will be started on the background, so that gconftool-2 can be used to see how the program reacts to changing parameters:

<nowiki>
[sbox-DIABLO_X86: ~/gconf-listener] > make
cc -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/gconf/2 \
-I/usr/include/dbus-1.0 -I/usr/lib/dbus-1.0/include -Wall -g \
-DPROGNAME=\"gconf-key-watch\" gconf-key-watch.c -o gconf-key-watch \
-lgconf-2 -ldbus-glib-1 -ldbus-1 -lgobject-2.0 -lglib-2.0
[sbox-DIABLO_X86: ~/gconf-listener] > run-standalone.sh ./gconf-key-watch &
[2] 21385
gconf-key-watch:main Starting.
gconf-key-watch:main GType and GConfClient initialized.
gconf-key-watch: Value for key '/apps/Maemo/platdev_ex/connection'
is set to 'btcomm0'
gconf-key-watch: Value for key '/apps/Maemo/platdev_ex/connectionparams'
is set to '9600,8,N,1'
gconf-key-watch:main Added /apps/Maemo/platdev_ex.
gconf-key-watch:main CB registered & starting main loop
[sbox-DIABLO_X86: ~/gconf-listener] > gconftool-2 --set --type string \
/apps/Maemo/platdev_ex/connection ttyS0
gconf-key-watch: keyChangeCallback invoked.
gconf-key-watch: Connection type setting changed: [ttyS0]
gconf-key-watch: keyChangeCallback done.
[sbox-DIABLO_X86: ~/gconf-listener] > gconftool-2 --set --type string \
/apps/Maemo/platdev_ex/connectionparams ''
gconf-key-watch: keyChangeCallback invoked.
gconf-key-watch: Connection params setting changed: []
gconf-key-watch: keyChangeCallback done.
</nowiki>

The latter change is somewhat problematic (which the code needs to deal with as well). It is necessary to decide how to react to values that are of the correct type, but with senseless values. GConf in itself does not provide syntax checking for the values, or any semantic checking support. It is recommended that configuration changes will only be reacted to when they pass some internal (to the application) logic that will check their validity, both at syntax level and also at semantic level.

One option would also be resetting the value back to a valid value, whenever the program detects an invalid value set attempt. This will lead to a lot of problems, if the value is set programmatically from another program that will obey the same rule, so it is not advisable. Quitting the program on invalid values is also an option that should not be used, since the restricted environment does not provide many ways to inform the user that the program has quit.

An additional possible problem is having multiple keys that are all "related" to a single setting or action. It is necessary to decide, how to deal with changes across multiple GConf keys that are related, yet changed separately. The two key example code demonstrates the inherent problem: should the server re-initialize the (theoretic) connection, when the connection key is changed, or when the connectionparams key is changed? If the connection is re-initialized when either of the keys is changed, then the connection will be re-initialized twice when both are changed "simultaneously" (user presses "Apply" on a settings dialog, or gconftool-2 is run and sets both keys). It is easy to see how this might be an even larger problem, if instead of two keys, there were five per connection. GConf and the GConfClient GObject wrapper that has been used here do not support "configuration set transactions", which would allow setting and processing multiple related keys using an atomic model. The example program ignores this issue completely.

The next step is to test how the program (which is still running) reacts to other problematic situations:

[sbox-DIABLO_X86: ~/gconf-listener] > gconftool-2 --set --type int \
/apps/Maemo/platdev_ex/connectionparams 5
gconf-key-watch: keyChangeCallback invoked.
gconf-key-watch: Connection params setting changed: [5]
gconf-key-watch: keyChangeCallback done.
[sbox-DIABLO_X86: ~/gconf-listener] > gconftool-2 --set --type boolean \
/apps/Maemo/platdev_ex/connectionparams true
gconf-key-watch: keyChangeCallback invoked.
gconf-key-watch: Connection params setting changed: [true]
gconf-key-watch: keyChangeCallback done.

The next example removes the configuration keys, while the program is still running:

[sbox-DIABLO_X86: ~/gconf-listener] > make clearkeys
gconf-key-watch: keyChangeCallback invoked.
gconf-key-watch[21403]: GLIB ERROR ** default -
file gconf-key-watch.c: line 129 (keyChangeCallback):
assertion failed: (value != NULL)
aborting...
/usr/bin/run-standalone.sh: line 11: 21403 Aborted (core dumped) "$@"
[1]+ Exit 134 run-standalone.sh ./gconf-key-watch

Since the code (in the callback function) contains an assert that checks for non-NULL values, it will abort when the key is removed, and that causes the value to go to NULL. So the abortion in the above case is expected.

Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/GnomeVFS File System

Maemo — Wed, 02 Sep 2009 12:24:34 GMT

Maemo: /* File System - GnomeVFS */

= File System - GnomeVFS =

Maemo includes a powerful file system framework, GnomeVFS. This framework enables applications to use a vast number of different file access protocols without having to know anything about the underlying details. Some examples of the supported protocols are: local file system, HTTP, FTP and OBEX over Bluetooth.

In practice, this means that all GnomeVFS file access methods are transparently available for both developer and end user just by using the framework for file operations. The API for file handling is also much more flexible than the standard platform offerings. It features, for example, asynchronous reading and writing, MIME type support and file monitoring.

All user-file access should be done with GnomeVFS in maemo applications, because file access can be remote. In fact, many applications that come with the operating system on the Maemo compatible device do make use of GnomeVFS. Access to files not visible to the user should be done directly for performance reasons.

A good hands-on starting point is taking a look at the GnomeVFS example in maemo-examples package. Detailed API information can be found in the [http://library.gnome.org/devel/gnome-vfs-2.0/stable/ GnomeVFS API reference]

==GnomeVFS Example==

This section uses the following example:
* [https://garage.maemo.org/svn/maemoexamples/trunk/support-libraries/hildon_helloworld-8.c hildon_helloworld-8.c]

In maemo, GnomeVFS also provides some filename case insensitivity support, so that the end users do not have to care about the UNIX filename conventions, which are case-sensitive.

The GnomeVFS interface attempts to provide a POSIX-like interface, so that where with POSIX you would use open(), in GnomeVFS you can use gnome_vfs_open; and instead of write(), you can use gnome_vfs_write, etc. The GnomeVFS function names are sometimes a bit more verbose, but otherwise they attempt to implement the basic API. Some POSIX functions, such as mmap(), are impossible to implement in the user space, but normally this is not a big problem. Also some functions fail to work over network connections and outside the local filesystem.

For a simple example of using the GnomeVFS interface functions, see below.

In order to save and load data, at least the following functions are needed:

* '''gnome_vfs_init()'''<nowiki>: initializes the GnomeVFS library. Needs to be done once at an early stage at program startup. </nowiki>
* '''gnome_vfs_shutdown()'''<nowiki>: frees up resources inside the library and closes it down. </nowiki>
* '''gnome_vfs_open()'''<nowiki>: opens the given URI (explained below) and returns a file handle for that if successful. </nowiki>
* '''gnome_vfs_get_file_info()'''<nowiki>: get information about a file (similar to, but with broader scope than fstat). </nowiki>
* '''gnome_vfs_read()'''<nowiki>: read data from an opened file. </nowiki>
* '''gnome_vfs_write()'''<nowiki>: write data into an opened file. </nowiki>

In order to differentiate between different protocols, GnomeVFS uses Uniform Resource 2 syntax when accessing resources. For example in '''file:///tmp/somefile.txt''', the file:// is the protocol to use, and the rest is the location within that protocol space for the resource or file to manipulate. Protocols can be stacked inside a single URI, and the URI also supports username and password combinations (these are best demonstrated in the GnomeVFS API documentation).

The following simple demonstration will be using local files.

A simple application will be extended in the following ways:

* Implement the "Open" command by using GnomeVFS with full error checking.
* The memory will be allocated and freed with g_malloc0() and g_free(), when loading the contents of the file that the user has selected.
* Data loaded through "Open" will replace the text in the GtkLabel that is in the center area of the HildonWindow. The label will be switched to support Pango simple text [http://maemo.org/api_refs/4.0/pango/PangoMarkupFormat.html markup], which looks a lot like simple HTML.
* Notification about loading success and failures will be communicated to the user by using a widget called HildonBanner, which will float a small notification dialog (with an optional icon) in the top-right corner for a while, without blocking the application.
* N.B. Saving into a file is not implemented in this code, as it is a lab exercise (and it is simpler than opening).
* File loading failures can be simulated by attempting to load an empty file. Since empty files are not wanted, the code will turn this into an error as well. If no empty file is available, one can easily be created with the touch command (under '''MyDocs''', so that the open dialog can find it). It is also possible to attempt to load a file larger than 100 KiB, since the code limits the file size (artificially), and will refuse to load large files.
* The goto statement should normally be avoided. Team coding guidelines should be checked to see, whether this is an allowed practice. Note how it is used in this example to cut down the possibility of leaked resources (and typing). Another option for this would be using variable finalizers, but not many people know how to use them, or even that they exist. They are gcc extensions into the C language, and you can find more about them by reading gcc info pages (look for variable attributes).
* Simple GnomeVFS functions are used here. They are all synchronous, which means that if loading the file takes a long time, the application will remain unresponsive during that time. For small files residing in local storage, this is a risk that is taken knowingly. Synchronous API should not be used when loading files over network due to the greater uncertainty.
* I/O in most cases will be slightly slower than using a controlled approach with POSIX I/O API (controlled meaning that one should know what to use and how). This is a price that has to be paid in order to enable easy switching to other protocols later.

N.B. Since GnomeVFS is a separate library from GLib, you will have to add the flags and library options that it requires. The pkg-config package name for the library is <code>gnome-vfs-2.0</code>.

<tt>''/**''
'' * hildon_helloworld-8.c''
'' *''
'' * This maemo code example is licensed under a MIT-style license,''
'' * that can be found in the file called "License" in the same''
'' * directory as this file.''
'' * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.''
'' *''
'' * We add file loading support using GnomeVFS. Saving files using''
'' * GnomeVFS is left as an exercise. We also add a small notification''
'' * widget (HildonBanner).''
'' *''
'' * Look for lines with "NEW" or "MODIFIED" in them.''
'' */''

'''<nowiki>#include</nowiki>''' <stdlib.h>
'''<nowiki>#include</nowiki>''' <hildon/hildon-program.h>
'''<nowiki>#include</nowiki>''' <hildon/hildon-color-button.h>
'''<nowiki>#include</nowiki>''' <hildon/hildon-find-toolbar.h>
'''<nowiki>#include</nowiki>''' <hildon/hildon-file-chooser-dialog.h>
''/* A small notification window widget (NEW). */''
'''<nowiki>#include</nowiki>''' <hildon/hildon-banner.h>
''/* Pull in the GnomeVFS headers (NEW). */''
'''<nowiki>#include</nowiki>''' <libgnomevfs/gnome-vfs.h>

''/* Declare the two slant styles. */''
'''enum''' {
STYLE_SLANT_NORMAL <nowiki>=</nowiki> 0,
STYLE_SLANT_ITALIC
}<nowiki>;</nowiki>

''/**''
'' * The application state.''
'' */''
'''typedef''' '''struct''' {
gboolean styleUseUnderline<nowiki>;</nowiki>
gboolean styleSlant<nowiki>;</nowiki>

GdkColor currentColor<nowiki>;</nowiki>

''/* Pointer to the label so that we can modify its contents when a''
'' file is loaded by the user (NEW). */''
GtkWidget<nowiki>*</nowiki> textLabel<nowiki>;</nowiki>

gboolean fullScreen<nowiki>;</nowiki>

GtkWidget<nowiki>*</nowiki> findToolbar<nowiki>;</nowiki>
GtkWidget<nowiki>*</nowiki> mainToolbar<nowiki>;</nowiki>
gboolean findToolbarIsVisible<nowiki>;</nowiki>
gboolean mainToolbarIsVisible<nowiki>;</nowiki>

HildonProgram<nowiki>*</nowiki> program<nowiki>;</nowiki>
HildonWindow<nowiki>*</nowiki> window<nowiki>;</nowiki>
} ApplicationState<nowiki>;</nowiki>

''/*... Listing cut for brevity ...*/''

''/**''
'' * Utility function to print a GnomeVFS I/O related error message to''
'' * standard error (not seen by the user in graphical mode) (NEW).''
'' */''
'''static''' void '''dbgFileError'''(GnomeVFSResult errCode, '''const''' gchar<nowiki>*</nowiki> uri) {
'''g_printerr'''("Error while accessing '%s': %s\n", uri,
'''gnome_vfs_result_to_string'''(errCode));
}

''/**''
'' * MODIFIED (A LOT)''
'' *''
'' * We read in the file selected by the user if possible and set the''
'' * contents of the file as the new Label content.''
'' *''
'' * If reading the file fails, the label will be left unchanged.''
'' */''
'''static''' void '''cbActionOpen'''(GtkWidget<nowiki>*</nowiki> widget, ApplicationState<nowiki>*</nowiki> app) {

gchar<nowiki>*</nowiki> filename <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
''/* We need to use URIs with GnomeVFS, so declare one here. */''
gchar<nowiki>*</nowiki> uri <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''g_assert'''(app <nowiki>!=</nowiki> NULL);
''/* Bad things will happen if these two widgets don't exist. */''
'''g_assert'''('''GTK_IS_LABEL'''(app->textLabel));
'''g_assert'''('''GTK_IS_WINDOW'''(app->window));

'''g_print'''("cbActionOpen invoked\n");

''/* Ask the user to select a file to open. */''
filename <nowiki>=</nowiki> '''runFileChooser'''(app, GTK_FILE_CHOOSER_ACTION_OPEN);
'''if''' (filename) {
''/* This will point to loaded data buffer. */''
gchar<nowiki>*</nowiki> buffer <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
''/* Pointer to a structure describing an open GnomeVFS "file". */''
GnomeVFSHandle<nowiki>*</nowiki> fileHandle <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
''/* Structure to hold information about a "file", initialized to''
'' zero. */''
GnomeVFSFileInfo fileInfo <nowiki>=</nowiki> {}<nowiki>;</nowiki>
''/* Result code from the GnomeVFS operations. */''
GnomeVFSResult result<nowiki>;</nowiki>
''/* Size of the file (in bytes) that we'll read in. */''
GnomeVFSFileSize fileSize <nowiki>=</nowiki> 0<nowiki>;</nowiki>
''/* Number of bytes that were read in successfully. */''
GnomeVFSFileSize readCount <nowiki>=</nowiki> 0<nowiki>;</nowiki>

'''g_print'''(" you chose to load file '%s'\n", filename);

''/* Convert the filename into an GnomeVFS URI. */''
uri <nowiki>=</nowiki> '''gnome_vfs_get_uri_from_local_path'''(filename);
''/* We don't need the original filename anymore. */''
'''g_free'''(filename);
filename <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
''/* Should not happen since we got a filename before. */''
'''g_assert'''(uri <nowiki>!=</nowiki> NULL);
''/* Attempt to get file size first. We need to get information''
'' about the file and aren't interested in other than the very''
'' basic information, so we'll use the INFO_DEFAULT setting. */''
result <nowiki>=</nowiki> '''gnome_vfs_get_file_info'''(uri, &fileInfo,
GNOME_VFS_FILE_INFO_DEFAULT);
'''if''' (result <nowiki>!=</nowiki> GNOME_VFS_OK) {
''/* There was a failure. Print a debug error message and break''
'' out into error handling. */''
'''dbgFileError'''(result, uri);
'''goto''' error<nowiki>;</nowiki>
}

''/* We got the information (maybe). Let's check whether it''
'' contains the data that we need. */''
'''if''' (fileInfo.valid_fields & GNOME_VFS_FILE_INFO_FIELDS_SIZE) {
''/* Yes, we got the file size. */''
fileSize <nowiki>=</nowiki> fileInfo.size<nowiki>;</nowiki>
} '''else''' {
'''g_printerr'''("Couldn't get the size of file!\n");
'''goto''' error<nowiki>;</nowiki>
}

''/* By now we have the file size to read in. Check for some limits''
'' first. */''
'''if''' (fileSize > 1024<nowiki>*</nowiki>100) {
'''g_printerr'''("Loading over 100KiB files is not supported!\n");
'''goto''' error<nowiki>;</nowiki>
}
''/* Refuse to load empty files. */''
'''if''' (fileSize <nowiki>==</nowiki> 0) {
'''g_printerr'''("Refusing to load an empty file\n");
'''goto''' error<nowiki>;</nowiki>
}

''/* Allocate memory for the contents and fill it with zeroes.''
'' NOTE:''
'' We leave space for the terminating zero so that we can pass''
'' this buffer as gchar to string functions and it is''
'' guaranteed to be terminated, even if the file doesn't end''
'' with binary zero (odds of that happening are small). */''
buffer <nowiki>=</nowiki> '''g_malloc0'''(fileSize+1);
'''if''' (buffer <nowiki>==</nowiki> NULL) {
'''g_printerr'''("Failed to allocate %u bytes for buffer\n",
(guint)fileSize);
'''goto''' error<nowiki>;</nowiki>
}

''/* Open the file.''

'' Parameters:''
'' - A pointer to the location where to store the address of the''
'' new GnomeVFS file handle (created internally in open).''
'' - uri: What to open (needs to be GnomeVFS URI).''
'' - open-flags: Flags that tell what we plan to use the handle''
'' for. This will affect how permissions are checked by the''
'' Linux kernel. */''

result <nowiki>=</nowiki> '''gnome_vfs_open'''(&fileHandle, uri, GNOME_VFS_OPEN_READ);
'''if''' (result <nowiki>!=</nowiki> GNOME_VFS_OK) {
'''dbgFileError'''(result, uri);
'''goto''' error<nowiki>;</nowiki>
}
''/* File opened succesfully, read its contents in. */''
result <nowiki>=</nowiki> '''gnome_vfs_read'''(fileHandle, buffer, fileSize,
&readCount);
'''if''' (result <nowiki>!=</nowiki> GNOME_VFS_OK) {
'''dbgFileError'''(result, uri);
'''goto''' error<nowiki>;</nowiki>
}
''/* Verify that we got the amount of data that we requested.''
'' NOTE:''
'' With URIs it won't be an error to get less bytes than you''
'' requested. Getting zero bytes will however signify an''
'' End-of-File condition. */''
'''if''' (fileSize <nowiki>!=</nowiki> readCount) {
'''g_printerr'''("Failed to load the requested amount\n");
''/* We could also attempt to read the missing data until we have''
'' filled our buffer, but for simplicity, we'll flag this''
'' condition as an error. */''
'''goto''' error<nowiki>;</nowiki>
}

''/* Whew, if we got this far, it means that we actually managed to''
'' load the file into memory. Let's set the buffer contents as''
'' the new label now. */''
'''gtk_label_set_markup'''('''GTK_LABEL'''(app->textLabel), buffer);

''/* That's it! Display a message of great joy. For this we'll use''
'' a dialog (non-modal) designed for displaying short''
'' informational messages. It will linger around on the screen''
'' for a while and then disappear (in parallel to our program''
'' continuing). */''
'''hildon_banner_show_information'''('''GTK_WIDGET'''(app->window),
NULL, ''/* Use the default icon (info). */''
"File loaded successfully");

''/* Jump to the resource releasing phase. */''
'''goto''' release<nowiki>;</nowiki>

error<nowiki>:</nowiki>
''/* Display a failure message with a stock icon.''
'' Please see ''http://maemo.org/api_refs/4.0/gtk/gtk-Stock-Items.html
'' for a full listing of stock items. */''
'''hildon_banner_show_information'''('''GTK_WIDGET'''(app->window),
GTK_STOCK_DIALOG_ERROR, ''/* Use the stock error icon. */''
"Failed to load the file");

release<nowiki>:</nowiki>
''/* Close and free all resources that were allocated. */''
'''if''' (fileHandle) '''gnome_vfs_close'''(fileHandle);
'''if''' (filename) '''g_free'''(filename);
'''if''' (uri) '''g_free'''(uri);
'''if''' (buffer) '''g_free'''(buffer);
''/* Zero them all out to prevent stack-reuse-bugs. */''
fileHandle <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
filename <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
uri <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
buffer <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''return'''<nowiki>;</nowiki>
} '''else''' {
'''g_print'''(" you didn't choose any file to open\n");
}
}

''/**''
'' * MODIFIED (kind of)''
'' *''
'' * Function to save the contents of the label (although it doesn't''
'' * actually save the contents, on purpose). Use gtk_label_get_label''
'' * to get a gchar pointer into the application label contents''
'' * (including current markup), then use gnome_vfs_create and''
'' * gnome_vfs_write to create the file (left as an exercise).''
'' */''
'''static''' void '''cbActionSave'''(GtkWidget<nowiki>*</nowiki> widget, ApplicationState<nowiki>*</nowiki> app) {
gchar<nowiki>*</nowiki> filename <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''g_assert'''(app <nowiki>!=</nowiki> NULL);

'''g_print'''("cbActionSave invoked\n");

filename <nowiki>=</nowiki> '''runFileChooser'''(app, GTK_FILE_CHOOSER_ACTION_SAVE);
'''if''' (filename) {
'''g_print'''(" you chose to save into '%s'\n", filename);
''/* Process saving .. */''

'''g_free'''(filename);
filename <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
} '''else''' {
'''g_print'''(" you didn't choose a filename to save to\n");
}
}

''/*... Listing cut for brevity ...*/''

''/**''
'' * MODIFIED''
'' *''
'' * Add support for GnomeVFS (it needs to be initialized before use)''
'' * and add support for the Pango markup feature of the GtkLabel''
'' * widget.''
'' */''
int '''main'''(int argc, char<nowiki>**</nowiki> argv) {

ApplicationState aState <nowiki>=</nowiki> {}<nowiki>;</nowiki>

GtkWidget<nowiki>*</nowiki> label <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
GtkWidget<nowiki>*</nowiki> vbox <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
GtkWidget<nowiki>*</nowiki> mainToolbar <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
GtkWidget<nowiki>*</nowiki> findToolbar <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

''/* Initialize the GnomeVFS (NEW). */''
'''if'''(!'''gnome_vfs_init'''()) {
'''g_error'''("Failed to initialize GnomeVFS-libraries, exiting\n");
}

''/* Initialize the GTK+ */''
'''gtk_init'''(&argc, &argv);

''/* Setup the HildonProgram, HildonWindow and application name. */''
aState.program <nowiki>=</nowiki> '''HILDON_PROGRAM'''('''hildon_program_get_instance'''());
'''g_set_application_name'''("Hello Hildon!");
aState.window <nowiki>=</nowiki> '''HILDON_WINDOW'''('''hildon_window_new'''());
'''hildon_program_add_window'''(aState.program,
'''HILDON_WINDOW'''(aState.window));

''/* Create the label widget, with Pango marked up content (NEW). */''
label <nowiki>=</nowiki> '''gtk_label_new'''("Hello Hildon (with Hildon"
"search and GnomeVFS "
"and other trickstm)!");

''/* Allow lines to wrap (NEW). */''
'''gtk_label_set_line_wrap'''('''GTK_LABEL'''(label), TRUE);

''/* Tell the GtkLabel widget to support the Pango markup (NEW). */''
'''gtk_label_set_use_markup'''('''GTK_LABEL'''(label), TRUE);

''/* Store the widget pointer into the application state so that the''
'' contents can be replaced when a file will be loaded (NEW). */''
aState.textLabel <nowiki>=</nowiki> label<nowiki>;</nowiki>

'''buildMenu'''(&aState);

vbox <nowiki>=</nowiki> '''gtk_vbox_new'''(FALSE, 0);
'''gtk_container_add'''('''GTK_CONTAINER'''(aState.window), vbox);
'''gtk_box_pack_end'''('''GTK_BOX'''(vbox), label, TRUE, TRUE, 0);

mainToolbar <nowiki>=</nowiki> '''buildToolbar'''(&aState);
findToolbar <nowiki>=</nowiki> '''buildFindToolbar'''(&aState);

aState.mainToolbar <nowiki>=</nowiki> mainToolbar<nowiki>;</nowiki>
aState.findToolbar <nowiki>=</nowiki> findToolbar<nowiki>;</nowiki>

''/* Connect the termination signals. */''
'''g_signal_connect'''('''G_OBJECT'''(aState.window), "delete-event",
'''G_CALLBACK'''(cbEventDelete), &aState);
'''g_signal_connect'''('''G_OBJECT'''(aState.window), "destroy",
'''G_CALLBACK'''(cbActionTopDestroy), &aState);

''/* Show all widgets that are contained by the Window. */''
'''gtk_widget_show_all'''('''GTK_WIDGET'''(aState.window));

''/* Add the toolbars to the Hildon Window. */''
'''hildon_window_add_toolbar'''('''HILDON_WINDOW'''(aState.window),
'''GTK_TOOLBAR'''(mainToolbar));
'''hildon_window_add_toolbar'''('''HILDON_WINDOW'''(aState.window),
'''GTK_TOOLBAR'''(findToolbar));

''/* Register a callback to handle key presses. */''
'''g_signal_connect'''('''G_OBJECT'''(aState.window), "key_press_event",
'''G_CALLBACK'''(cbKeyPressed), &aState);

'''g_print'''("main: calling gtk_main\n");
'''gtk_main'''();
'''g_print'''("main: returned from gtk_main and exiting with success\n");

'''return''' EXIT_SUCCESS<nowiki>;</nowiki>
}
</tt>

[[Image:hildon_helloworld-8-ok.png|Image hildon_helloworld-8-ok]] 
[[Image:hildon_helloworld-8-failed.png|Image hildon_helloworld-8-failed]]

In order to experiment with loading other content, a simple file can be created, containing Pango markup like this: '''echo "Hello world" > MyDocs/hello.txt''' , and then loading hello.txt.

As can be imagined, these examples have only scratched the surface of GnomeVFS that is quite a rich library, and contains a broad API and a large amount of plug-ins. Many things have been completely avoided, such as directory content iteration, the asynchronous interface, callback signaling on directory content changes etc. Please see [http://library.gnome.org/devel/gnome-vfs-2.0/stable/ GnomeVFS API reference] for more information. The API also contains some mini tutorials on various GnomeVFS topics, so it is well worth the time spent reading. It will also show that GnomeVFS has been overloaded with functions, which are not even file operation related (such as ZeroConf and creating TCP/IP connections etc.).

GTK+ does not have to be used in order to use GnomeVFS. One such example program is Midnight Commander (a Norton Commander clone, but better), which is a menu-based "text" mode program. GnomeVFS uses GLib though, so if using GnomeVFS, one should think about using GLib as well, as it will be loaded anyway.

Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Extending Hildon Input Methods

Maemo — Wed, 02 Sep 2009 12:19:49 GMT

Maemo: moved Maemo 5 Developer Guide/Generic Platform Components/ Extending Hildon Input Methods to Maemo 5 Developer Guide/Generic Platform Components/Extending Hildon Input Methods

= Extending Hildon Input Methods =

== Overview ==

Maemo platform is intended to be used on embedded devices. It is a quite straightforward request that one might want to have different input methods from the ones available by default, or just simply want a different layout for the virtual keyboard. For this reason, maemo 4.1 introduces a way to enable writing custom plug-ins for Hildon Input Method.

This section describes writing a simple plug-in for Hildon Input Method. This example plug-in is going to implement a very basic virtual keyboard.

The illustration below shows what area of the Hildon Input Method can be redefined with the custom plug-in.

<div align="CENTER">[[Image:HIM-ui.png|Image HIM-ui]]</div>

Technically, the plug-in is an almost standard GTK widget (with additional steps to support dynamic loading). The widget of the plug-in will be placed in the Plug-in area.

The illustration below shows the data flow of a user's input:

<div align="CENTER">[[Image:HIM-comp.png|Image HIM-comp]]</div>

User inputs directly to the plug-in, then the plug-in sends the inputted data to HIM main user interface. The HIM main UI will interact with the IM context, and then commit the inputted text to the client widget.

In case of a custom plug-in, the plug-in itself - i.e. its writer - is responsible for handling all the inputs (even the buttons that are part of HIM main UI, e.g. tab or enter) and propagate them to the right modules (e.g. IM context).

The function and outlook of the buttons in HIM main UI can be customized, but one cannot remove them completely from the UI - only dim them (see handwriting plug-in), and they cannot be rearranged (for further information, see section Common buttons).

== Plug-in features ==

Hildon Input Method plug-in must be a GTK widget. In addition to the GTK widget interface, the plug-in must implement certain functions.

=== Interface ===

As already mentioned, the plug-in must handle all the inputs - both real user input and management signals from the system - that are coming to the HIM main UI. The first step is to take a look at which functions need to be implemented and provided by the plug-in to the Hildon Input Method Plug-in Interface. Later on, it will be shown how these functions are actually registered for the HIM Plug-in Interface.

The essential functions that must be implemented by a basic plug-in:

* hildon-input-method/hildon-im-plugin.h
<tt>void (*enable) (HildonIMPlugin <nowiki>*</nowiki>plugin, gboolean init);
</tt>
'''enable''' is called whenever the plug-in becomes available to the user. '''init''' holds TRUE whenever this is the initialization time. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the plugin is available to the user */''
'''static''' void
'''enable''' (HildonIMPlugin <nowiki>*</nowiki>plugin, gboolean init)
{
HimExampleVKBPrivate <nowiki>*</nowiki>priv<nowiki>;</nowiki>
HimExampleVKB <nowiki>*</nowiki>vkb<nowiki>;</nowiki>
vkb <nowiki>=</nowiki> '''HIMEXAMPLE_VKB''' (plugin);
priv <nowiki>=</nowiki> '''HIMEXAMPLE_VKB_GET_PRIVATE''' (vkb);
'''if''' (init <nowiki>==</nowiki> TRUE)
{
'''hildon_im_ui_button_set_toggle''' (priv->ui,
HILDON_IM_BUTTON_MODE_A, TRUE);
'''hildon_im_ui_button_set_toggle''' (priv->ui,
HILDON_IM_BUTTON_MODE_B, TRUE);
'''hildon_im_ui_button_set_label''' (priv->ui,
HILDON_IM_BUTTON_MODE_A, "ABC");
'''hildon_im_ui_button_set_label''' (priv->ui,
HILDON_IM_BUTTON_MODE_B, "Shift");
}
'''hildon_im_ui_send_communication_message'''(priv->ui, HILDON_IM_CONTEXT_DIRECT_MODE);
}</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*disable) (HildonIMPlugin <nowiki>*</nowiki>plugin);
</tt>
'''disable''' is called whenever the plug-in becomes unavailable to the user (e.g. when the main UI is closed). hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the plugin is disabled */''
'''static''' void
'''disable'''(HildonIMPlugin <nowiki>*</nowiki>plugin)
{
''/* not implemented */''
}</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*settings_changed) (HildonIMPlugin <nowiki>*</nowiki>plugin,
'''const''' gchar <nowiki>*</nowiki>key,
'''const''' GConfValue <nowiki>*</nowiki>value);
</tt>
'''settings_changed''' is called whenever the HIM main UI receives a notification from GConf about Hildon Input Method settings being changed. The affected settings are all settings residing in '''/apps/osso/inputmethod''' path. '''key''' and '''value''' hold the GConf key and its value respectively. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the standard input method settings ''
'' has been changed */''
'''static''' void
'''settings_changed''' (HildonIMPlugin <nowiki>*</nowiki>plugin,
'''const''' gchar <nowiki>*</nowiki>key, '''const''' GConfValue <nowiki>*</nowiki>value)
{
''/* not implemented */''
}</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*input_mode_changed) (HildonIMPlugin <nowiki>*</nowiki>plugin);
</tt>
'''input_mode_changed''' is called whenever the input mode is changed. Input mode is changed to what has been specified by the client widget. The input mode puts constraints to the plug-in to limit whether input shall be accepted or ignored. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when input mode changed */''
'''static''' void
'''input_mode_changed''' (HildonIMPlugin <nowiki>*</nowiki>plugin)
{
''/* not implemented */''
}
</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*clear) (HildonIMPlugin <nowiki>*</nowiki>plugin);
</tt>
'''clear''' is called whenever the HIM main UI requests the plug-in to clear or refresh its user interface. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the plugin is requested to 'clear'/refresh its UI */''
'''static''' void
'''clear'''(HildonIMPlugin <nowiki>*</nowiki>plugin)
{
''/* not implemented */''
}</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*client_widget_changed) (HildonIMPlugin <nowiki>*</nowiki>plugin);
</tt>
'''client_widget_changed''' is called whenever the client widget is changed from one to another. For instance, the case could be that the user taps on another text entry. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the client widget changed */''
'''static''' void
'''client_widget_changed''' (HildonIMPlugin <nowiki>*</nowiki>plugin)
{
''/* not implemented */''
}</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*save_data) (HildonIMPlugin <nowiki>*</nowiki>plugin);
</tt>
'''save_data''' is called whenever the HIM main UI is requested to save its (and the plug-in's) data. Usually it is called when the main UI is requested to quit. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the plugin is requested to save its data */''
'''static''' void
'''save_data'''(HildonIMPlugin <nowiki>*</nowiki>plugin)
{
''/* not implemented */''
}</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*mode_a) (HildonIMPlugin <nowiki>*</nowiki>plugin);
</tt>
'''mode_a''' is called whenever the ''Mode A'' (Caps Lock in virtual keyboard plug-in) is pressed. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the MODE_A button is pressed */''
'''static''' void
'''mode_a'''(HildonIMPlugin <nowiki>*</nowiki>plugin)
{
HimExampleVKBPrivate <nowiki>*</nowiki>priv<nowiki>;</nowiki>
HimExampleVKB <nowiki>*</nowiki>vkb<nowiki>;</nowiki>
vkb <nowiki>=</nowiki> '''HIMEXAMPLE_VKB''' (plugin);
priv <nowiki>=</nowiki> '''HIMEXAMPLE_VKB_GET_PRIVATE''' (vkb);
'''if''' ('''hildon_im_ui_button_get_active''' (priv->ui,
HILDON_IM_BUTTON_MODE_B)) {
'''hildon_im_ui_button_set_active''' (priv->ui,
HILDON_IM_BUTTON_MODE_B, FALSE);
'''if''' ('''hildon_im_ui_button_get_active''' (priv->ui,
HILDON_IM_BUTTON_MODE_A)) {
priv->case_mode <nowiki>=</nowiki> CASE_UPPER<nowiki>;</nowiki>
} '''else''' {
priv->case_mode <nowiki>=</nowiki> CASE_LOWER<nowiki>;</nowiki>
}
} '''else''' {
'''if''' ('''hildon_im_ui_button_get_active''' (priv->ui,
HILDON_IM_BUTTON_MODE_A)) {
priv->case_mode <nowiki>=</nowiki> CASE_UPPER<nowiki>;</nowiki>
} '''else''' {
priv->case_mode <nowiki>=</nowiki> CASE_LOWER<nowiki>;</nowiki>
}
}
'''update_layout''' (vkb);
}</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*mode_b) (HildonIMPlugin <nowiki>*</nowiki>plugin);
</tt>
'''mode_b''' is called whenever the ''Mode B'' (Shift in virtual keyboard plug-in) is pressed. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the MODE_B button is pressed */''
'''static''' void
'''mode_b'''(HildonIMPlugin <nowiki>*</nowiki>plugin)
{
HimExampleVKBPrivate <nowiki>*</nowiki>priv<nowiki>;</nowiki>
HimExampleVKB <nowiki>*</nowiki>vkb<nowiki>;</nowiki>
vkb <nowiki>=</nowiki> '''HIMEXAMPLE_VKB''' (plugin);
priv <nowiki>=</nowiki> '''HIMEXAMPLE_VKB_GET_PRIVATE''' (vkb);
'''if''' ('''hildon_im_ui_button_get_active''' (priv->ui,
HILDON_IM_BUTTON_MODE_B)) {
'''if''' ('''hildon_im_ui_button_get_active''' (priv->ui,
HILDON_IM_BUTTON_MODE_A)) {
priv->case_mode <nowiki>=</nowiki> CASE_LOWER<nowiki>;</nowiki>
} '''else''' {
priv->case_mode <nowiki>=</nowiki> CASE_UPPER<nowiki>;</nowiki>
}
} '''else''' {
'''if''' ('''hildon_im_ui_button_get_active''' (priv->ui,
HILDON_IM_BUTTON_MODE_A)) {
priv->case_mode <nowiki>=</nowiki> CASE_UPPER<nowiki>;</nowiki>
} '''else''' {
priv->case_mode <nowiki>=</nowiki> CASE_LOWER<nowiki>;</nowiki>
}
}
'''update_layout''' (vkb);
}</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*backspace) (HildonIMPlugin <nowiki>*</nowiki>plugin);
</tt>
'''backspace''' is called whenever the virtual backspace key is pressed. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the backspace button is pressed */''
'''static''' void
'''backspace''' (HildonIMPlugin <nowiki>*</nowiki>plugin)
{
HimExampleVKBPrivate <nowiki>*</nowiki>priv<nowiki>;</nowiki>
priv <nowiki>=</nowiki> '''HIMEXAMPLE_VKB_GET_PRIVATE''' ('''HIMEXAMPLE_VKB''' (plugin));
'''hildon_im_ui_send_communication_message''' (priv->ui,
HILDON_IM_CONTEXT_HANDLE_BACKSPACE);
}</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*enter) (HildonIMPlugin <nowiki>*</nowiki>plugin);
</tt>
'''enter''' is called whenever the virtual enter key is pressed. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the enter button is pressed */''
'''static''' void
'''enter''' (HildonIMPlugin <nowiki>*</nowiki>plugin)
{
HimExampleVKBPrivate <nowiki>*</nowiki>priv<nowiki>;</nowiki>
priv <nowiki>=</nowiki> '''HIMEXAMPLE_VKB_GET_PRIVATE''' ('''HIMEXAMPLE_VKB''' (plugin));
'''hildon_im_ui_send_communication_message''' (priv->ui,
HILDON_IM_CONTEXT_HANDLE_ENTER);
}</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*tab) (HildonIMPlugin <nowiki>*</nowiki>plugin);
</tt>
'''tab''' is called whenever the virtual tab key is pressed. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the tab button is pressed */''
'''static''' void
'''tab''' (HildonIMPlugin <nowiki>*</nowiki>plugin)
{
HimExampleVKBPrivate <nowiki>*</nowiki>priv<nowiki>;</nowiki>
priv <nowiki>=</nowiki> '''HIMEXAMPLE_VKB_GET_PRIVATE''' ('''HIMEXAMPLE_VKB''' (plugin));
'''hildon_im_ui_send_communication_message''' (priv->ui,
HILDON_IM_CONTEXT_HANDLE_TAB);
}</tt>

Couple of functions related to changing language:

* hildon-input-method/hildon-im-plugin.h
<tt>void (*language) (HildonIMPlugin <nowiki>*</nowiki>plugin);
</tt>
'''language''' is called whenever a new language is selected from the HIM main UI menu. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Called when the language has been changed */''
'''static''' void
'''language''' (HildonIMPlugin <nowiki>*</nowiki>plugin)
{
''/* not implemented */''
}</tt>
* hildon-input-method/hildon-im-plugin.h
<tt>void (*language_settings_changed) (HildonIMPlugin <nowiki>*</nowiki>plugin, gint index);
</tt>
'''language_settings_changed''' is called whenever the language settings for the specified language index have been changed.

=== Plug-in Loading ===

A nature of a plug-in is that it can be dynamically loaded. In this case also, the HIM plug-in is loaded whenever the user selects it, so in order to support the dynamic loading, the plug-in has to provide the following three specific functions for Hildon Input Method plug-in system:

* <tt>void '''module_init''' (GTypeModule <nowiki>*</nowiki>module);
</tt>
This function initializes the plug-in as a module, meaning the type of GTypeInfo needs to be registered, and the interface and instance information (GInterfaceInfo) need to be added to the module. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>void
'''module_init'''(GTypeModule <nowiki>*</nowiki>module)
{
'''static''' '''const''' GTypeInfo type_info <nowiki>=</nowiki> {
'''sizeof'''(HimExampleVKBClass),
NULL, ''/* base_init */''
NULL, ''/* base_finalize */''
(GClassInitFunc) himExample_vkb_class_init,
NULL, ''/* class_finalize */''
NULL, ''/* class_data */''
'''sizeof'''(HimExampleVKB),
0, ''/* n_preallocs */''
(GInstanceInitFunc) himExample_vkb_init,
}<nowiki>;</nowiki>
'''static''' '''const''' GInterfaceInfo plugin_info <nowiki>=</nowiki> {
(GInterfaceInitFunc) himExample_vkb_iface_init,
NULL, ''/* interface_finalize */''
NULL, ''/* interface_data */''
}<nowiki>;</nowiki>
himExample_vkb_type <nowiki>=</nowiki>
'''g_type_module_register_type'''(module,
GTK_TYPE_WIDGET, "HimExampleVKB",
&type_info,
0);
'''g_type_module_add_interface'''(module,
HIMEXAMPLE_VKB_TYPE,
HILDON_IM_TYPE_PLUGIN,
&plugin_info);
}</tt>
The '''himExample_vkb_iface_init''' function should register the custom interface functions in '''HildonIMPluginIface'''<nowiki>: </nowiki>hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Standard GTK stuff */''
'''static''' void
'''himExample_vkb_iface_init''' (HildonIMPluginIface <nowiki>*</nowiki>iface)
{
iface->enable <nowiki>=</nowiki> enable<nowiki>;</nowiki>
iface->disable <nowiki>=</nowiki> disable<nowiki>;</nowiki>
iface->enter <nowiki>=</nowiki> enter<nowiki>;</nowiki>
iface->tab <nowiki>=</nowiki> tab<nowiki>;</nowiki>
iface->backspace <nowiki>=</nowiki> backspace<nowiki>;</nowiki>
iface->clear <nowiki>=</nowiki> clear<nowiki>;</nowiki>
iface->input_mode_changed <nowiki>=</nowiki> input_mode_changed<nowiki>;</nowiki>
iface->client_widget_changed <nowiki>=</nowiki> client_widget_changed<nowiki>;</nowiki>
iface->save_data <nowiki>=</nowiki> save_data<nowiki>;</nowiki>
iface->language <nowiki>=</nowiki> language<nowiki>;</nowiki>
iface->mode_a <nowiki>=</nowiki> mode_a<nowiki>;</nowiki>
iface->mode_b <nowiki>=</nowiki> mode_b<nowiki>;</nowiki>
iface->language_settings_changed <nowiki>=</nowiki> language_settings_changed<nowiki>;</nowiki>
iface->settings_changed <nowiki>=</nowiki> settings_changed<nowiki>;</nowiki>
'''return'''<nowiki>;</nowiki>
}</tt>
* <tt>void '''module_exit''' (void);
</tt>
This function defines actions when the module is unloaded from the memory. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>void
'''module_exit'''(void)
{
''/* empty */''
}</tt>
* <tt>HildonIMPlugin<nowiki>*</nowiki> '''module_create''' (HildonIMUI <nowiki>*</nowiki>ui);
</tt>
This function creates and returns the plug-in widget to the main UI. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>HildonIMPlugin<nowiki>*</nowiki>
'''module_create''' (HildonIMUI <nowiki>*</nowiki>keyboard)
{
'''return''' '''HILDON_IM_PLUGIN''' ('''himExample_vkb_new''' (keyboard));
}</tt>

=== Plug-in Info ===

Some basic information of the plug-in needs to be provided to the HIM plug-in system, so it can keep up with the kinds of plug-ins that are available in the system. This is performed with two specific functions:

* <tt>'''const''' HildonIMPluginInfo<nowiki>*</nowiki> '''hildon_im_plugin_get_info'''(void);
</tt>
The function creates '''HildonIMPluginInfo''' struct for providing the required information. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/* Input Method plugin information.''
'' * This structure tells the main UI about this plugin */''
'''const''' HildonIMPluginInfo <nowiki>*</nowiki>
'''hildon_im_plugin_get_info'''(void)
{
'''static''' '''const''' HildonIMPluginInfo info <nowiki>=</nowiki>
{
"HIM VKB Example", ''/* description */''
"himExample_vkb", ''/* name */''
"Keyboard (EXAMPLE)", ''/* menu title */''
NULL, ''/* gettext domain */''
TRUE, ''/* visible in menu */''
FALSE, ''/* cached */''
HILDON_IM_TYPE_DEFAULT, ''/* UI type */''
HILDON_IM_GROUP_LATIN, ''/* group */''
HILDON_IM_DEFAULT_PLUGIN_PRIORITY, ''/* priority */''
NULL, ''/* special character plugin */''
"", ''/* help page */''
FALSE, ''/* disable common UI buttons */''
HILDON_IM_DEFAULT_HEIGHT, ''/* plugin height */''
HILDON_IM_TRIGGER_STYLUS ''/* trigger */''
}<nowiki>;</nowiki>
'''return''' &info<nowiki>;</nowiki>
}</tt>
* <tt>gchar<nowiki>**</nowiki> '''hildon_im_plugin_get_available_languages''' (gboolean <nowiki>*</nowiki>free);
</tt>
The function returns a NULL terminated array of string, containing language codes supported by the plug-in. Set '''free''' to '''TRUE''' if HIM main UI should free the returned value when no longer used. hildon-input-method-plugins-example/src/him-vkb-example.c
<tt>''/*''
'' * This function returns the list of available languages supported''
'' * by the plugin.''
'' * */''
gchar <nowiki>**</nowiki>
'''hildon_im_plugin_get_available_languages''' (gboolean <nowiki>*</nowiki>free)
{
'''static''' gchar <nowiki>*</nowiki>list[] <nowiki>=</nowiki> { "en_GB", NULL }<nowiki>;</nowiki>
<nowiki>*</nowiki>free <nowiki>=</nowiki> FALSE<nowiki>;</nowiki>
'''return''' list<nowiki>;</nowiki>
}</tt>

== Interaction with main user interface ==

As mentioned above, the plug-in is placed inside the HIM main UI. This section deals with interacting with it. This is mainly done by calling its functions, as defined in '''hildon-im-ui.h'''.

=== Handling Input ===

hildon-input-method/hildon-im-ui.h

<tt>void '''hildon_im_ui_send_utf8'''(HildonIMUI <nowiki>*</nowiki>main_ui, '''const''' gchar <nowiki>*</nowiki>text);</tt>

The plug-in can request the main UI to commit a UTF-8 encoded text by calling this function. hildon-input-method/hildon-im-ui.h

<tt>void '''hildon_im_ui_send_communication_message'''(HildonIMUI <nowiki>*</nowiki>main_ui, gint message);</tt>

The plug-in can use this function to tell the main UI that '''Enter''', '''Backspace''', or '''Tab''' virtual buttons are pressed. Simply call this function and pass one of the constants below as the '''message''' argument:

* <code>HILDON_IM_CONTEXT_HANDLE_ENTER</code>
* <code>HILDON_IM_CONTEXT_HANDLE_BACKSPACE</code>
* <code>HILDON_IM_CONTEXT_HANDLE_TAB</code>

=== UI Visibility ===

hildon-input-method/hildon-im-ui.h

<tt>void '''hildon_im_ui_set_visible'''(HildonIMUI <nowiki>*</nowiki>ui, gboolean visible);</tt>

The plug-in can request the main UI to set it's visibility by calling this function. hildon-input-method/hildon-im-ui.h

<tt>gboolean '''hildon_im_ui_get_visibility'''(HildonIMUI <nowiki>*</nowiki>main_ui);</tt>

By calling this function, the plug-in can get the visibility status of the main UI.

=== Get Input Method State ===

The following two state reader functions could be very handy in case the plug-in receives a state change notification (e.g. language change), because this way all the state information does not need to be saved. hildon-input-method/hildon-im-ui.h

<tt>HildonIMCommand '''hildon_im_ui_get_autocase_mode'''(HildonIMUI <nowiki>*</nowiki>main_ui);</tt>

The function returns the auto-capitalization mode of the current client widget. hildon-input-method/hildon-im-ui.h

<tt>'''const''' gchar <nowiki>*</nowiki> '''hildon_im_ui_get_active_language'''(HildonIMUI <nowiki>*</nowiki>main_ui);</tt>

The function returns the current language code.

=== Common Buttons ===

As mentioned in the ''Overview'' section, the outlook and even the function of the buttons in the main UI can be modified. '''N.B.''' It is not recommended to alter buttons, except the ''Mode A'' and ''Mode B'' buttons! Other buttons may have hardwired behavior within the main UI.

If the plug-in changes the functionality of a button, one might want to reflect this also in the UI by changing the label of the button. The layout of the buttons can be altered by the following two functions:

* hildon-input-method/hildon-im-ui.h
<tt>void '''hildon_im_ui_button_set_label'''(HildonIMUI <nowiki>*</nowiki>keyboard,
HildonIMButton button,
'''const''' gchar <nowiki>*</nowiki>label);
</tt>
With this function, the plug-in can set the label of a button.
Possible values of '''HildonIMButton''' (see '''hildon-im-ui.h'''):
** <code>HILDON_IM_BUTTON_TAB</code>
** <code>HILDON_IM_BUTTON_MODE_A</code>
** <code>HILDON_IM_BUTTON_MODE_B</code>
** <code>HILDON_IM_BUTTON_INPUT_MENU</code>
** <code>HILDON_IM_BUTTON_BACKSPACE</code>
** <code>HILDON_IM_BUTTON_ENTER</code>
** <code>HILDON_IM_BUTTON_SPECIAL_CHAR</code>
** <code>BUTTON_CLOSE</code>
* hildon-input-method/hildon-im-ui.h
<tt>void '''hildon_im_ui_button_set_id'''(HildonIMUI <nowiki>*</nowiki>self,
HildonIMButton button,
'''const''' gchar <nowiki>*</nowiki>id);
</tt>
This function sets a name to a particular button.

Since every input to the HIM main UI is caught by the plug-in, it is necessary to keep the button state (active or in-active) in sync. The state of a particular button can be changed, queried and toggled with the following functions:

* hildon-input-method/hildon-im-ui.h
<tt>void '''hildon_im_ui_button_set_active'''(HildonIMUI <nowiki>*</nowiki>keyboard,
HildonIMButton button,
gboolean active);
</tt>
This function sets the active state of a particular button.
* hildon-input-method/hildon-im-ui.h
<tt>gboolean '''hildon_im_ui_button_get_active'''(HildonIMUI <nowiki>*</nowiki>keyboard,
HildonIMButton button);
</tt>
This function returns the active state of a particular button.
* hildon-input-method/hildon-im-ui.h
<tt>void '''hildon_im_ui_button_set_toggle'''(HildonIMUI <nowiki>*</nowiki>keyboard,
HildonIMButton button,
gboolean toggle);
</tt>
The plug-in can set the toggle state of a particular button with this function.

Miscellaneous button manipulation functions:

* hildon-input-method/hildon-im-ui.h
<tt>void '''hildon_im_ui_button_set_menu'''(HildonIMUI <nowiki>*</nowiki>keyboard,
HildonIMButton button,
GtkWidget <nowiki>*</nowiki>menu);
</tt>
With this function, the plug-in can attach a menu - which is a GtkWidget - to a particular button.
* hildon-input-method/hildon-im-ui.h
<tt>void '''hildon_im_ui_button_set_sensitive'''(HildonIMUI <nowiki>*</nowiki>keyboard,
HildonIMButton button,
gboolean sensitive);
</tt>
All the buttons defined on the HIM main UI may not be needed, or the functionality of a button may be wished to be switched off in some states. In this case, the sensitivity of a particular button can be set by calling this function.
* hildon-input-method/hildon-im-ui.h
<tt>void '''hildon_im_ui_button_set_repeat'''(HildonIMUI <nowiki>*</nowiki>keyboard,
HildonIMButton button,
gboolean repeat);
</tt>
This function controls whether a particular button will repeat when pressed for a long time.

== Component dependencies ==

At least the following headers shall be included in the plug-in:

<tt>'''<nowiki>#include</nowiki>''' <hildon-im-plugin.h>
'''<nowiki>#include</nowiki>''' <hildon-im-ui.h></tt>

'''hildon-input-method-framework-dev''' and '''libhildon-im-ui-dev''' packages.

== Language codes ==

These are the language codes recognized; they are numbered, the first, af_ZA, being 0.

af_ZA am_ET ar_AE ar_BH ar_DZ ar_EG ar_IN ar_IQ ar_JO ar_KW
ar_LB ar_LY ar_MA ar_OM ar_QA ar_SA ar_SD ar_SY ar_TN ar_YE
az_AZ be_BY bg_BG bn_IN br_FR bs_BA ca_ES cs_CZ cy_GB da_DK
de_AT de_BE de_CH de_DE de_LU el_GR en_AU en_BW en_CA en_DK
en_GB en_HK en_IE en_IN en_NZ en_PH en_SG en_US en_ZA en_ZW
eo_EO es_AR es_BO es_CL es_CO es_CR es_DO es_EC es_ES es_GT
es_HN es_MX es_NI es_PA es_PE es_PR es_PY es_SV es_US es_UY
es_VE et_EE eu_ES fa_IR fi_FI fo_FO fr_BE fr_CA fr_CH fr_FR
fr_LU ga_IE gd_GB gl_ES gv_GB he_IL hi_IN hr_HR hu_HU hy_AM
id_ID is_IS it_CH it_IT iw_IL ja_JP ka_GE kl_GL ko_KR kw_GB
lt_LT lv_LV mi_NZ mk_MK mr_IN ms_MY mt_MT nl_BE nl_NL nn_NO
no_NO oc_FR pl_PL pt_BR pt_PT ro_RO ru_RU ru_UA se_NO sk_SK
sl_SI sq_AL sr_YU sv_FI sv_SE ta_IN te_IN tg_TJ th_TH ti_ER
ti_ET tl_PH tr_TR tt_RU uk_UA ur_PK uz_UZ vi_VN wa_BE yi_US
zh_CN zh_HK zh_SG zh_TW

Documentation/Maemo 5 Developer Guide/Architecture/UI Framework

Maemo — Mon, 31 Aug 2009 13:31:05 GMT

Maemo: /* Status menu plugin API */

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

==System Decomposition view==

===Subsystems in UI framework domain===
{|cellspacing="0" border="1" width="70%"
|'''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
|-
|I18 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]]

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

{|cellspacing="0" border="1" width="70%"
|'''Attribute'|'''Value'''
|-
|service||(ignored)
|-
|interface||com.nokia.ke_recv.bgkill_on
|-
|object path||/com/nokia/ke-recv/bgkill_on
|-
|member||bgkill_on
|}

{|cellspacing="0" border="1" width="70%"
|'''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.

{|cellspacing="0" border="1" width="70%"
|'''Attribute'''||'''Value'''
|-
|service||(ignored)
|-
|interface||com.nokia.ke_recv.lowmem_on
|-
|object path||/com/nokia/ke-recv/lowmem_on
|-
|member||bgkill_off
|}

{|cellspacing="0" border="1" width="70%"
|'''Attribute'''||'''Value'''
|-
|service||(ignored)
|-
|interface||com.nokia.ke_recv.lowmem_off
|-
|object path||/com/nokia/ke-recv/lowmem_off
|-
|member||bgkill_off
|}

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

{|cellspacing="0" border="1" width="70%"
|'''Attribute'''||'''Value'''
|-
|service||(ignored)
|-
|interface||com.nokia.osso_app_killer
|-
|object path||/com/nokia/osso_app_killer
|-
|member||exit
|}

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

{|cellspacing="0" border="1" width="70%"
|'''Attribute'''||'''Value'''
|-
|service||(ignored)
|-
|interface||org.maemo.launcher
|-
|object path||org/maemo/launcher
|-
|member||Application Died
|}

{|cellspacing="0" border="1" width="70%"
|'''Argument #'''||'''Mandatory'''||'''Type'''||'''Value'''
|-
|1||yes||DBUS TYPE STRING||ﬁle name of the executable
|-
|2||yes||DBUS TYPE INT32||PID of the died process
|-
|3||yes||DBUS TYPE INT32||exit code returned from waitpid()
|}

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

{|cellspacing="0" border="1" width="70%"
|'''Attribute'''||'''Value'''
|-
|service||(ignored)
|-
|interface||com.nokia.hildon_desktop
|-
||object path||(ignored)
|-
|member||exit_app_view
|}

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

{|cellspacing="0" border="1" width="70%"
|'''Attribute'''||'''Value'''
|-
|service||(ignored)
|-
|interface||com.nokia.mce.signal
|-
|object path||com/nokia/mce/signal
|-
|member||shutdown_ind
|}

====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 [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]]

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

{|cellspacing="0" border="1" width="70%"
|'''Attribute'''||'''Value'''
|-
|service||org.freedesktop.Notifications
|-
|interface||org.freedesktop.Notifications
|–
|object path||/org/freedesktop/Notifications
|-
|member||SystemNoteInfoprint
|}

{|cellspacing="0" border="1" width="70%"
|'''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 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.

{|cellspacing="0" border="1" width="70%"
|'''Attribute'''||'''Value'''
|-
|'''service'''||org.freedesktop.Notifications
|-
|'''interface'''||org.freedesktop.Notifications
|-
|'''object path'''||/org/freedesktop/Notifications
|-
|'''member'''||SystemNoteDialog
|}

{|cellspacing="0" border="1" width="70%"
|'''Argument #'''||'''Mandatory'''||'''Type'''||'''Value'''
|-
|1||yes||DBUS TYPE STRING||message to show
|-
|2||yes||DBUT_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 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.:

<?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>

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

[[Image:hildon-statusmenu_decomposition.png|800px]]

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

Documentation/Maemo 5 Developer Guide/Architecture/Top Level Architecture

Maemo — Mon, 31 Aug 2009 13:15:23 GMT

Maemo: Created page with '=Maemo 5 Software Architecture= The following figure gives a logical decomposition view of Maemo 5 software architecture based on the domains delivering software to the Fremantle…'

=Maemo 5 Software Architecture=
The following figure gives a logical decomposition view of Maemo 5 software architecture based on the domains delivering software to the Fremantle release.

''Note: The components marked in red are proprietary components.''

[[Image:top_level_architecture.png|800px]]

'''Core Domain''' contains bootloader and Calibration Area, Linux kernel, X windowing system (X11), OpenGL ES, and (some) essential user space components (the C library, essential user space tools, and system configuration data and tools) adapted / configured for the Fremantle HW.

'''System Software domain''' is responsible for user modes, device states including start-up/shutdown, display and other inactivity state control, providing robustness services, power management, and battery management.

'''Connectivity domain''' provides the APIs, user interfaces and underlying user-space and kernel components for Wireless Internet, Wireless local and Home connectivity, implements connection establishment mechanisms and user interfaces to control Internet access points on the device. This includes WLAN, connections over Bluetooth, also UPnP, and Device Management (uses the Funambol OMA DM/DS framework).

'''RTCom domain''' provides both services, and applications, for realtime Internet communications (Voice Over IP calls and Instant Messaging) on
Maemo platform. It also provides and distributes presence information within the system and is responsible for smooth integration of the externally developed Skype application into the system.

'''Multimedia Framework domain''' contains the multimedia APIs including GStreamer, ALSA and PulseAudio, and the lower level functionality such as DSP codecs. Multimedia Framework also responsible for policy, audio-routing, and event-sounds.

'''Location domain''' implements a framework that applications can use to become location aware. Location implements also an API that provides a set of location related utilities like geocoding, reverse geocoding, show on map, select from map, get map data and POI (Point Of Interest) repository. It also includes everything related to GPS and SUPL.

'''Toolkit domain''' contains the graphical UI libraries to draw content on the device’s screen and used by the applications to create user graphical interfaces.

'''Desktop domain''' contains Window Manager and Clutter, Home, Status Menu, and their plugins, Control Panel and its applets, Input Methods and I18N, and application services such as Startup.

'''Data Management domain''' consists of application and user data related subsystems. It also includes GConf.

'''Applications domain''' provides end user applications like Browser, Email, Calendar, Games etc provides public interfaces for 3rd party applications to access them.

'''Graphics domain''' provides sounds, icons and pre-installed content for the device.