Documentation/Maemo 5 Developer Guide/Application Development/Writing a new maemo application

= Introduction =

This section is a guide for making new applications for the Maemo platform. Maemo 5 SDK needs to be installed successfully as a pre-requisite.

A simple text editor with a few essential features is used as a example. Let us name it as MaemoPad.

MaemoPad has the following basic features: New, Open, Save, Save As..., Cut, Copy, Paste, Font, Full Screen, Full Screen hardware key handling, Send-Via email/bluetooth and Close. For simplicity, it does not contain advanced features like ``Undo, ``Redo, different fonts in one document, pictures, tables, etc.

The figure below is a screenshot of the text editor.



= Creating the application file structure =

In general, a maemo application uses @@LINK@@ GNU build system and has the following files and subdirectories:
 * : Contains the source files.
 * : Contains the files related to debian packaging
 * : Contains all data files needed to run the application. Maemopad will need the following data files:
 * file
 * D-Bus  file
 * application icons in a separate directory called
 * : Contains the localization files. Maemopad contains the following files:
 * list the names of the files to be localized.
 * Translation file  containing British English strings for the application.
 * Translation file  containing Finnish strings for the application.
 * is a shell script that provides automatic build system preparation.
 * is an input file for  that contains   macros that test the system features the package needs or can use. It produces the   script.
 * is used by  to produce a standards-compliant  . The   in the top source directory is usually very simple and includes the files and subdirectories needed to make the application:   and all the  s in   directories.

You can compile the source as follows: [sbox-FREMANTLE_X86 ~] > ./autogen.sh  [sbox-FREMANTLE_X86 ~] >$ ./configure [sbox-FREMANTLE_X86 ~] >$ make

For more information about GNU autoconf and automake, see chapter GNU build system

= Coding the application =

The src/ directory of MaemoPad contains the following files:
 * main.c
 * maemopad-window.h
 * maemopad-window.c
 * fullscreenmanager.c
 * fullscreenmanage.h
 * Makefile.am

maemopad-window.h
defines the  structure to hold the application data and other declarations. Even though the data varies depending on the application, a sample structure might look like this:

typedef struct _MaemopadWindow MaemopadWindow; struct _MaemopadWindow { HildonWindow parent; /* Osso context, needed for "send via" functionality. */  osso_context_t *osso; /* Fullscreen mode is on (TRUE) or off (FALSE): */ gboolean fullscreen; /* Button items for menu: */ GtkWidget *new_item; GtkWidget *open_item; GtkWidget *save_item; GtkWidget *saveas_item; GtkWidget *cut_item; GtkWidget *copy_item; GtkWidget *paste_item; /*.....more...truncated...*/ }

Where MaemopadWindow is a structure containing pointers to all the UI objects, such as HildonWindow, menu items, toolbar; and UI-related data, for instance a boolean variable indicating whether the application is in fullscreen mode.

Each application creates its own AppData variable, and this variable is usually passed around as a parameter in the functions, particularly the callback functions, so that the applications data can be accessible by the functions.

Many applications declare this AppData variable as global.

main.c
main.c usually performs, at least, the following functions:


 * Initializing GTK
 * Initializing localization
 * Creating an instance of HildonProgram
 * Calling to a function, usually defined in interface.c, to create the main view.
 * Connecting the main view window to the created HildonProgram
 * Running
 * Connecting the  of the main view to a callback function to handle a proper application exit, such as destroying the main view window, freeing used memory and saving application states before exit.
 * Call

Here is the main function of MaemoPad with comments:

int main (int argc, char* argv[]) { osso_context_t *osso = NULL; AppData *data = g_new0 (AppData, 1); /* Initialize the locale stuff: */ setlocale (LC_ALL, ""); bindtextdomain (GETTEXT_PACKAGE, LOCALEDIR); bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8"); textdomain (GETTEXT_PACKAGE); /* Inititialize GTK+ and hildon: */ hildon_gtk_init (&argc, &argv); if (!g_thread_supported) { g_thread_init (NULL); } /* Create the hildon application and setup the title: */ data->program = HILDON_PROGRAM (hildon_program_get_instance ); g_set_application_name (_("MaemoPad")); /* We need the osso context to call libmodest_dbus_client_compose_mail later. */  osso = osso_initialize (OSSO_SERVICE, VERSION, TRUE, NULL); g_assert (osso); /* Create the window for our application: */ data->window = maemopad_window_new (osso); hildon_program_add_window (data->program, data->window); /* Show the main window and start the mainloop, * quitting the mainloop when it the main window is hidden: */  gtk_widget_show (GTK_WIDGET (data->window)); g_signal_connect(data->window, "hide", G_CALLBACK (&on_main_window_hide), NULL); g_signal_connect(data->window, "delete_event",    G_CALLBACK (&gtk_widget_hide_on_delete), NULL); gtk_main; /* Clean up: */ gtk_widget_destroy (GTK_WIDGET (data->window)); g_free (data); return 0; }

= User interface =

The graphical user interface code is implemented in directory ./src/ui/. It contains two .c files: interface.c and callbacks.c

interface.c
This file creates the graphical user interface (GUI) and connects the signals and events to appropriate handlers defined in callbacks.c. See section for information on how to create GUI in Maemo. For more information on GTK see the GTK+ Reference Manual /node22.html.

As a general practice, an AppUIData struct variable is created when creating the GUI. And then, a HildonWindow and smaller components are created in different functions, such as,. When creating each component, AppUIData should refer various necessary UI objects created along the way.

The following excerpt shows how AppUIData is created, and how it points to the toolbar and the button ``New file'' on the toolbar.

  /* Creates and initializes a main_view */  AppUIData  *  interface_main_view_new   ( AppData  * data ) {  /* Zero memory with g_new0 */  AppUIData  * result  =  g_new0   ( AppUIData ,  1  );  <font color="#9A1900">/*....*/   <font color="#000000">create_toolbar  <font color="#990000">( result <font color="#990000">);  <font color="#9A1900">/*....*/  <font color="#FF0000">}  <font color="#9A1900">/* Create toolbar to mainview */   <font color="#0000FF">static  <font color="#009900">void   <font color="#000000">create_toolbar   <font color="#990000">( AppUIData <font color="#990000"> * main <font color="#990000">) <font color="#FF0000">{  <font color="#9A1900">/* Create new GTK toolbar */  main <font color="#990000">-&gt; toolbar <font color="#990000"> =  <font color="#000000">gtk_toolbar_new   <font color="#990000">;  <font color="#9A1900">/*....*/   <font color="#9A1900">/* Create the "New file" button in the toolbar */  main <font color="#990000">-&gt; new_tb <font color="#990000"> =  <font color="#000000">gtk_tool_button_new_from_stock   <font color="#990000">( GTK_STOCK_NEW <font color="#990000">);  <font color="#9A1900">/*....*/  <font color="#FF0000">} </tt>

callbacks.c
callbacks.c defines all the functions that handle the signals or events that might be triggered by the UI. When creating different UI objects in interface.c, the handlers are registered as follows.

<tt>  <font color="#9A1900">/* Create the menu items needed for the drop down menu */   <font color="#0000FF">static  <font color="#009900">void   <font color="#000000">create_menu   <font color="#990000">( AppUIData <font color="#990000"> * main <font color="#990000">) <font color="#FF0000">{ '' <font color="#9A1900">/* ... */ ''     main <font color="#990000">-&gt; new_item <font color="#990000"> =   <font color="#000000">gtk_menu_item_new_with_label   <font color="#990000">(   <font color="#000000">_   <font color="#990000">(  <font color="#FF0000">"New"  <font color="#990000">)  <font color="#990000">); '' <font color="#9A1900">/* ... */       <font color="#9A1900">/* Attach the callback functions to the activate signal */ ''  <font color="#000000">g_signal_connect  <font color="#990000">(   <font color="#000000">G_OBJECT   <font color="#990000">( main <font color="#990000">-&gt; new_item <font color="#990000">),  <font color="#FF0000">"activate"  <font color="#990000">,                         <font color="#000000">G_CALLBACK   <font color="#990000">( callback_file_new <font color="#990000">), main <font color="#990000">); '' <font color="#9A1900">/* ... */ '' <font color="#FF0000">} </tt>

Function callback_file_new is implemented in callbacks.c, saving the current file if needed, and then opening a new file to edit.

<tt> <font color="#009900">void  <font color="#000000">callback_file_new   <font color="#990000">( GtkAction <font color="#990000"> * action <font color="#990000">, gpointer data <font color="#990000">) <font color="#FF0000">{ gint answer <font color="#990000"> ; AppUIData <font color="#990000"> * mainview <font color="#990000"> = NULL <font color="#990000"> ; mainview <font color="#990000"> = <font color="#990000">( AppUIData <font color="#990000"> *  <font color="#990000">) data <font color="#990000"> ;  <font color="#000000">g_assert  <font color="#990000">( mainview <font color="#990000"> != NULL <font color="#990000">&amp;&amp; mainview <font color="#990000">-&gt; data <font color="#990000"> != NULL <font color="#990000">);  <font color="#9A1900">/* save changes note if file is edited */   <font color="#0000FF">if  <font color="#990000">( mainview <font color="#990000">-&gt; file_edited <font color="#990000">)  <font color="#FF0000">{ answer <font color="#990000"> =  <font color="#000000">interface_save_changes_note   <font color="#990000">( mainview <font color="#990000">);  <font color="#0000FF">if  <font color="#990000">( answer <font color="#990000"> == CONFRESP_YES <font color="#990000">)  <font color="#FF0000">{  <font color="#0000FF">if  <font color="#990000">( mainview <font color="#990000">-&gt; file_name <font color="#990000"> == NULL <font color="#990000">)  <font color="#FF0000">{ mainview <font color="#990000">-&gt; file_name <font color="#990000"> =  <font color="#000000">interface_file_chooser   <font color="#990000">( mainview <font color="#990000">, GTK_FILE_CHOOSER_ACTION_SAVE <font color="#990000">); <font color="#FF0000">}  <font color="#000000">write_buffer_to_file  <font color="#990000">( mainview <font color="#990000">); <font color="#FF0000">} <font color="#FF0000">}  <font color="#9A1900">/* clear buffer, filename and free buffer text */   <font color="#000000">gtk_text_buffer_set_text  <font color="#990000">(   <font color="#000000">GTK_TEXT_BUFFER   <font color="#990000">( mainview <font color="#990000">-&gt; buffer <font color="#990000">),  <font color="#FF0000">""  <font color="#990000">,  <font color="#990000">-  <font color="#993399">1  <font color="#990000">); mainview <font color="#990000">-&gt; file_name <font color="#990000"> = NULL <font color="#990000"> ; mainview <font color="#990000">-&gt; file_edited <font color="#990000"> = FALSE <font color="#990000"> ; <font color="#FF0000">} </tt>

N.B. The AppUIData struct variable mainview is retrieved in such a way that the handlers can have a direct effect on the UI for the users.

MaemoPad contains many functions:


 * File Save/Save-As/Open: This uses HildonFileChooserDialog.
 * Edit Cut/Copy/Paste: This uses Clipboard ([/node13.html#sec:clipboard_usage 12.2])
 * Hardware keys: MaemoPad can recognize the ``Fullscreen`` button key presses (F6). It switches the application from fullscreen mode to normal mode, and vice versa. Many other hardware key events can be added to MaemoPad, see section [localhost#sec:hardware_keys 8.3.3].
 * Font/Color Selector: These are explained in HildonFontSelectionDialog and HildonColorChooser.
 * Send via Email/Bluetooth: Refer to section  ``Send via functionality  [/node13.html#sec:send_via_functionality 12.3] on chapter Using Generic Platform Components'' of Maemo Reference Manual for instructions on how to implement Send via functionality.

More information on GTK Widgets can be found on the GTK+ Reference Manual.

interface.h
In the interface header file interface.h, public functions are defined for main.c and callbacks.c. In the case of MaemoPad, confirmation responses for the save changes note, MaemopadError enum for the Hildon error note and the AppUIData are also defined here. N.B. AppUIData can also be defined in appdata.h in some other applications. MaemoPad's interface.h looks like this:

<tt>  <font color="#000080"> #define  MAIN_VIEW_NAME <font color="#FF0000">"AppUIData"  <font color="#0000FF">typedef   <font color="#0000FF">enum   <font color="#FF0000">{ MAEMOPAD_NO_ERROR <font color="#990000"> = <font color="#993399">0  <font color="#990000">, MAEMOPAD_ERROR_INVALID_URI <font color="#990000">, MAEMOPAD_ERROR_SAVE_FAILED <font color="#990000">, MAEMOPAD_ERROR_OPEN_FAILED <font color="#FF0000">} MaemopadError <font color="#990000"> ;  <font color="#9A1900">/* Struct to include view's information */   <font color="#0000FF">typedef   <font color="#0000FF">struct   <font color="#009900">_AppUIData AppUIData <font color="#990000"> ;  <font color="#0000FF">struct  <font color="#009900">_AppUIData <font color="#FF0000">{  <font color="#9A1900">/* Handle to app's data */  AppData <font color="#990000"> * data <font color="#990000"> ;  <font color="#9A1900">/* Fullscreen mode is on (TRUE) or off (FALSE) */  gboolean fullscreen <font color="#990000"> ;  <font color="#9A1900">/* Items for menu */  GtkWidget <font color="#990000"> * file_item <font color="#990000"> ; GtkWidget <font color="#990000"> * new_item <font color="#990000"> ; '' <font color="#9A1900">/* ... */ ''     GtkWidget <font color="#990000"> * font_item <font color="#990000"> ; GtkWidget <font color="#990000"> * fullscreen_item <font color="#990000"> ;  <font color="#9A1900">/* Toolbar */  GtkWidget <font color="#990000"> * toolbar <font color="#990000"> ; GtkWidget <font color="#990000"> * iconw <font color="#990000"> ; GtkToolItem <font color="#990000"> * new_tb <font color="#990000"> ; GtkToolItem <font color="#990000"> * open_tb <font color="#990000"> ; '' <font color="#9A1900">/* ... */       <font color="#9A1900">/* Textview related */ '' GtkWidget <font color="#990000"> * scrolledwindow <font color="#990000"> ;   <font color="#9A1900">/* textview is under this widget */  GtkWidget <font color="#990000"> * textview <font color="#990000"> ;         <font color="#9A1900">/* widget that shows the text */  GtkTextBuffer <font color="#990000"> * buffer <font color="#990000"> ;       <font color="#9A1900">/* buffer that contains the text */  GtkClipboard <font color="#990000"> * clipboard <font color="#990000"> ;     <font color="#9A1900">/* clipboard for copy/paste */  PangoFontDescription <font color="#990000"> * font_desc <font color="#990000"> ;    <font color="#9A1900">/* font used in textview */  gboolean file_edited <font color="#990000"> ;     <font color="#9A1900">/* tells is our file on view edited */  gchar <font color="#990000"> * file_name <font color="#990000"> ;         <font color="#9A1900">/* directory/file under editing */  <font color="#FF0000">} <font color="#990000"> ;  <font color="#9A1900">/* Public functions: */  AppUIData <font color="#990000"> *  <font color="#000000">interface_main_view_new   <font color="#990000">( AppData <font color="#990000"> * data <font color="#990000">); <font color="#009900">void  <font color="#000000">interface_main_view_destroy   <font color="#990000">( AppUIData <font color="#990000"> * main <font color="#990000">); <font color="#009900">char <font color="#990000"> *   <font color="#000000">interface_file_chooser   <font color="#990000">( AppUIData <font color="#990000"> * main <font color="#990000">, GtkFileChooserAction action <font color="#990000">); PangoFontDescription <font color="#990000"> *  <font color="#000000">interface_font_chooser   <font color="#990000">( AppUIData <font color="#990000"> * main <font color="#990000">); '' <font color="#9A1900">/* ... */ '' </tt>

= Localization =

Localization means translating the application into different languages. In Maemo, this is fairly easily performed by grouping all the strings needing translations into a .po file, giving them each an id, and then using the id in the code instead of hard-coded strings. The function used to generate the translated strings from an id in Maemo is the standard GNU.

Initialization
When the application runs,  is used to determine the correct language depending on the locale settings. The application initializes the text domain as follows:

<tt> <font color="#009900">int  <font color="#000000">main   <font color="#990000">(  <font color="#009900">int argc <font color="#990000">,  <font color="#009900">char  <font color="#990000"> * argv <font color="#990000">[]  <font color="#990000">) <font color="#FF0000">{ '' <font color="#9A1900">/* ... */       <font color="#9A1900">/* Initialize the locale stuff */ ''  <font color="#000000">setlocale  <font color="#990000">( LC_ALL <font color="#990000">,  <font color="#FF0000">""  <font color="#990000">);  <font color="#000000">bindtextdomain  <font color="#990000">( GETTEXT_PACKAGE <font color="#990000">, LOCALEDIR <font color="#990000">);  <font color="#000000">bind_textdomain_codeset  <font color="#990000">( GETTEXT_PACKAGE <font color="#990000">,  <font color="#FF0000">"UTF-8"  <font color="#990000">);  <font color="#000000">textdomain  <font color="#990000">( GETTEXT_PACKAGE <font color="#990000">); '' <font color="#9A1900">/* ... */ '' <font color="#FF0000">} </tt>

More information on localization can be found in section [/node17.html#sec:maemo_localization 16.4].

File structure
Localization files are stored in the po/ directory. The following files are used for MaemoPad localization:

Makefile.am POTFILES.in en_GB.po

POTFILES.in contains the list of the source code files to be localized. In MaemoPad, only main.c and interface.c contain strings that need to be localized.

<tt>  <font color="#9A1900"> # List of MaemoPad source files to be localized  <font color="#990000">.. /src/main <font color="#990000">. c <font color="#990000">.. /src/ui/interface <font color="#990000">. c</tt>

File en_GB.po includes translated text for British English. It contains pairs of id/string as follows:

<tt> '' <font color="#9A1900"> # ... '' msgid <font color="#FF0000">"maemopad_yes" msgstr <font color="#FF0000">"Yes" '' <font color="#9A1900"> # ... '' </tt>

N.B. The comments in .po file start with ``#``.

Using en_GB.po
The msgid(s) are passed to the GNU  function as a parameter to generate the translated string. In Maemo, the recommended way is

<tt>  <font color="#000080"> #define   <font color="#000000">_   <font color="#990000">( String <font color="#990000">)   <font color="#000000">gettext   <font color="#990000">( String <font color="#990000">) </tt>

Therefore, in MaemoPad, the string for Menu-&gt;File-&gt;Open menu is created as follows:

<tt>   main <font color="#990000">-&gt; open_item <font color="#990000"> =   <font color="#000000">gtk_menu_item_new_with_label   <font color="#990000">(   <font color="#000000">_   <font color="#990000">(  <font color="#FF0000">"Open"  <font color="#990000">)  <font color="#990000">); </tt>

8.8.5.4 Creating .po files from source
Sometimes code must be localized for applications that were not originally designed for localization. You can create .po files from source code using GNU xgettext[], by extracting all the strings from the source files into a template.po file

xgettext -f POTFILES.in -C -a -o template.po

Read the man page for xgettext for more information, in short:


 * ``-f POTFILES.in`` uses POTFILES.in to get the files to be localized
 * ``-C`` is for C-code type of strings
 * ``-a`` is for ensuring that we get all strings from specified files
 * ``-o template.po`` defines the output filename.

The next step is to copy this template.po into ./po/en_GB.po and add or edit all the strings in British English. Other languages can be handled in the same way.

= Adding application to menu =

See section [localhost#sec:getting_app_to_task_navigator_menu 8.6.1] for information on how to perform this. In short, the maemopad.desktop and com.nokia.maemopad.service files are stored in the ./data directory, and they look like this, respectively

(N.B. Whitespace is not allowed after the lines.)

= Link to Maemo menu =

When the Debian package is installed to Maemo platform, .desktop and .service files are used to link MaemoPad to the Task Navigator.

== Adding help =

Applications can have their own help files. Help files are XML files located under the  directory. Each language is located in its own subdirectory, such as  for British English help files. MaemoPad has  with very simple help content. The middle part of the contextUID must be the same as the help file name (without suffix):

<tt>  <font color="#000080">&lt;?xml  <font color="#009900">version  <font color="#990000"> =  <font color="#FF0000">"1.0"  <font color="#009900">encoding  <font color="#990000"> =  <font color="#FF0000">"UTF-8"   <font color="#000080">?&gt;   <font color="#0000FF">&lt;hildonhelpsource&gt;   <font color="#0000FF">&lt;folder&gt;   <font color="#0000FF">&lt;title&gt;  MaemoPad  <font color="#0000FF">&lt;/title&gt;   <font color="#0000FF">&lt;topic&gt;   <font color="#0000FF">&lt;topictitle&gt;  Main Topic  <font color="#0000FF">&lt;/topictitle&gt;   <font color="#0000FF">&lt;context  <font color="#009900">contextUID  <font color="#990000"> =  <font color="#FF0000">"Example_MaemoPad_Content"   <font color="#0000FF">/&gt;   <font color="#0000FF">&lt;para&gt;  This is a help file with example content.  <font color="#0000FF">&lt;/para&gt;   <font color="#0000FF">&lt;/topic&gt;   <font color="#0000FF">&lt;/folder&gt;   <font color="#0000FF">&lt;/hildonhelpsource&gt;  </tt>

By using  function (see hildon-help.h), this help content can be shown in the application. After creating a Help menu item, a callback function can be connected to it:

<tt> <font color="#009900">void  <font color="#000000">callback_help   <font color="#990000">( GtkAction <font color="#990000"> * action <font color="#990000">, gpointer data <font color="#990000">) <font color="#FF0000">{ osso_return_t retval <font color="#990000"> ;  <font color="#9A1900">/* connect pointer to our AppUIData struct */  AppUIData <font color="#990000"> * mainview <font color="#990000"> = NULL <font color="#990000"> ; mainview <font color="#990000"> = <font color="#990000">( AppUIData <font color="#990000"> *  <font color="#990000">) data <font color="#990000"> ;  <font color="#000000">g_assert  <font color="#990000">( mainview <font color="#990000"> != NULL <font color="#990000">&amp;&amp; mainview <font color="#990000">-&gt; data <font color="#990000"> != NULL <font color="#990000">); retval <font color="#990000"> =  <font color="#000000">hildon_help_show   <font color="#990000">(        mainview <font color="#990000">-&gt; data <font color="#990000">-&gt; osso <font color="#990000">,   <font color="#9A1900">/* osso_context */         HELP_TOPIC_ID <font color="#990000">,         <font color="#9A1900">/* topic id */         HILDON_HELP_SHOW_DIALOG <font color="#990000">); <font color="#FF0000">} </tt>

= Packaging the application =

A Debian package is an application packed in one file to make installing easy in Debian-based operating systems, like Maemo platform. More information about creating a Debian packages can be found in section Creating Debian packages [/node18.html#sec:creating_debian_packages 17.1] of Maemo Reference Manual Chapter Packaging, Deploying and Distributing. Our goal in this section is to create a Debian package of MaemoPad, to be installed in the Maemo platform.

If creating a package that can be installed using the Application Manager, see section Making application packages [/node18.html#sec:making_app_pack 17.2] of the same aforementioned chapter.

Creating debian/ Directory
In order to create the package, the following files are created in the debian/ directory:

changelog control copyright rules ... etc ...

The 'rules' file is the file defining how the Debian package is built. The 'rules' file tells where the files should be installed. Also a 'control' file is needed to define what kind of packages (often different language versions) are going to be created. Changelog and copyright files are also needed, or the package does not build. The 'changelog' file consists of the version number of the package, and a short description about changes compared to older versions. The 'copyright' file includes information in plain text about the package copyrights.

Most important lines in rules file are:

<tt>  <font color="#9A1900"> # Add here commands to install the package into debian/&lt;installation directory&gt;  <font color="#009900">$(MAKE) install <font color="#009900">DESTDIR <font color="#990000"> =  <font color="#009900">$(CURDIR) /debian <font color="#990000">/&lt; installation directory <font color="#990000">&gt; </tt>

These lines define where the package files are installed. debian/&lt;installation directory&gt; is used as a temporary directory for package construction.

Creating and building the package
The package is made using the following command:

dpkg-buildpackage -rfakeroot -uc -us -sa -D

The result should be these MaemoPad files:



A .deb file now exists. This package can be installed using ``fakeroot dpkg -i maemopad_x.x_i386.deb'' command. The icon to the application should now be in the Maemo Task Navigator menu, and it should be launchable from there. To remove the package, use the command ``fakeroot dpkg -r maemopad''.