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

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.

[[Image:Maemopad2.png|500px|alt=Screenshot of MaemoPad|MaemoPad text editor]]

== Creating the application file structure ==

In general, a Maemo application uses the [[../../GNU Build System|GNU Build System]] and has the following files and subdirectories:
* <code>src/</code>: Contains the source files.
* <code>debian/</code>: Contains the files related to Debian packaging
* <code>data/</code>: Contains all data files needed to run the application. Maemopad will need the following data files:
**<code>maemopad.desktop</code> file 
**D-Bus <code>maemopad.service</code> file 
**application icons in a separate directory called <code>icons/</code>
* <code>po/</code>: Contains the localization files. Maemopad contains the following files:
** <code>POTFILES.in</code> list the names of the files to be localized.
** Translation file <code>en_GB.po</code> containing British English strings for the application.
** Translation file <code>fi_FI.po</code> containing Finnish strings for the application.
* <code>autogen.sh</code> is a shell script that provides automatic build system preparation.
* <code>configure.ac</code> is an input file for <code>autoconf</code> that contains <code>autoconf</code> macros that test the system features the package needs or can use. It produces the <code>configure</code> script.
* <code>Makefile.am</code> is used by <code>automake</code> to produce a standards-compliant <code>Makefile.in</code>. The <code>Makefile.am</code> in the top source directory is usually very simple and includes the files and subdirectories needed to make the application: <code>src/</code>, <code>po/</code> and <code>data/</code> and all the <code>Makefile</code>s in <code>src/</code>, <code>po/</code>, and <code>data/</code> 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 the [[Documentation/Maemo 5 Developer Guide/GNU Build System|GNU build system]] article.

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

<code>[https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemopad/src/maemopad-window.h maemopad-window.h]</code> defines the <code>MaemopadWindow</code> 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:

<source lang="c">
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...*/
};
</source>

Where <code>MaemopadWindow</code> is a structure containing pointers to all the UI objects, such as <code>HildonWindow</code>, 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 <code>AppData</code> 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 <code>AppData</code> variable as global.

=== main.c ===

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

* Initializing GTK+
* Initializing localization
* Creating an instance of <code>HildonProgram</code>
* Calling to a function, usually defined in <code>interface.c</code>, to create the main view.
* Connecting the main view window to the created <code>HildonProgram</code>
* Running <code>gtk_main()</code>
* Connecting the <code>delete_event</code> 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 <code>gtk_main_quit()</code>

Here is the main function of MaemoPad with comments:

<source lang="c">
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;
}
</source>

== User interface ==

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

=== interface.c ===

This file creates the graphical user interface (GUI) and connects the signals and events to appropriate handlers defined in <code>callbacks.c</code>. See the [http://www.forum.nokia.com/info/sw.nokia.com/id/eb8a68ba-6225-4d84-ba8f-a00e4a05ff6f/Hildon_2_2_UI_Style_Guide.html Hildon UI style guide] for information on how to create GUI in Maemo. For more information on GTK+ see the [http://maemo.org/api_refs/5.0/5.0-final/gtk/ GTK+ Reference Manual].

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

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

<source lang="c">
/* Creates and initializes a main_view */
AppUIData* interface_main_view_new( AppData *data )
{
    /* Zero memory with g_new0 */
    AppUIData* result = g_new0( AppUIData, 1 );
    /*....*/
    create_toolbar( result );
    /*....*/
}
/* Create toolbar to mainview */
static void create_toolbar ( AppUIData *main )
{
    /* Create new GTK toolbar */
    main->toolbar = gtk_toolbar_new ();
    /*....*/
    /* Create the "New file" button in the toolbar */
    main->new_tb = gtk_tool_button_new_from_stock(GTK_STOCK_NEW);
    /*....*/
}
</source>

=== callbacks.c ===

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

<source lang="c">
/* Create the menu items needed for the drop down menu */
static void create_menu( AppUIData *main )
{
    /* ... */
    main->new_item = gtk_menu_item_new_with_label ( _("New") );
    /* ... */
    /* Attach the callback functions to the activate signal */
    g_signal_connect( G_OBJECT( main->new_item ), "activate",
                      G_CALLBACK ( callback_file_new), main );
    /* ... */
}
</source>

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

<source lang="c">
void callback_file_new(GtkAction * action, gpointer data)
{
    gint answer;
    AppUIData *mainview = NULL;
    mainview = ( AppUIData * ) data;
    g_assert(mainview != NULL && mainview->data != NULL );
    /* save changes note if file is edited */
    if( mainview->file_edited ) {
        answer = interface_save_changes_note( mainview );
        if( answer == CONFRESP_YES ) {
            if( mainview->file_name == NULL ) {
                mainview->file_name = interface_file_chooser(mainview, GTK_FILE_CHOOSER_ACTION_SAVE);
            }
            write_buffer_to_file ( mainview );
        }
    }
    /* clear buffer, filename and free buffer text */
    gtk_text_buffer_set_text ( GTK_TEXT_BUFFER (mainview->buffer), "", -1 );
    mainview->file_name = NULL;
    mainview->file_edited = FALSE;
}
</source>

N.B. The <code>AppUIData</code> struct variable <code>mainview</code> 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 <code>HildonFileChooserDialog</code>.
* Edit Cut/Copy/Paste: This uses the clipboard ([[Documentation/Maemo 5 Developer Guide/Using Data Sharing/Clipboard Usage|clipboard usage]])
* Font/Color Selector: These are explained in <code>HildonFontSelectionDialog</code> and <code>HildonColorChooser</code>.
* [[Documentation/Maemo 5 Developer Guide/Using Data Sharing/Sharing Plug-in#Writing .22Send Via.22 Functionality to E-mail and Bluetooth|Send via Email/Bluetooth]]

=== interface.h ===

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

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

== 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 <code>gettext()</code>.

===Initialization ===

When the application runs, <code>gettext()</code> is used to determine the correct language depending on the locale settings. The application initializes the text domain as follows:

<source lang="c">
int main( int argc, char* argv[] )
{
    /* ... */
    /* Initialize the locale stuff */
    setlocale ( LC_ALL, "" );
    bindtextdomain ( GETTEXT_PACKAGE, LOCALEDIR );
    bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
    textdomain ( GETTEXT_PACKAGE );
    /* ... */
}
</source>

More information on localization can be found in the [[Documentation/Maemo 5 Developer Guide/Application Development/Maemo Localization|Maemo localization]] section.

=== File structure ===

Localization files are stored in the <code>po/</code> directory. The following files are used for MaemoPad localization:

* <code>Makefile.am</code>
* <code>POTFILES.in</code>
* <code>en_GB.po</code>

<code>POTFILES.in</code> 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.

 # List of MaemoPad source files to be localized
 ../src/main.c
 ../src/ui/interface.c

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

 # ...
 msgid "maemopad_yes"
 msgstr "Yes"
 # ...

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

=== Using en_GB.po ===

The msgid(s) are passed to the GNU <code>gettext()</code> function as a parameter to generate the translated string. In Maemo, the recommended way is

<source lang="c">
#define _(String) gettext(String)
</source>

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

<source lang="c">
main->open_item = gtk_menu_item_new_with_label ( _("Open") );
</source>

==== 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 [http://www.gnu.org/software/gettext/ GNU xgettext], by extracting all the strings from the source files into a <code>template.po</code> file

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

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

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

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

== Adding application to menu ==

In short, the <code>maemopad.desktop</code> and <code>com.nokia.maemopad.service</code> files are stored in the <code>./data</code> directory, and they look like this, respectively:

 [Desktop Entry]
 Encoding=UTF-8
 Version=0.1
 Type=Application
 Name=MaemoPad
 Exec=/usr/bin/maemopad
 Icon=maemopad
 X-Window-Icon=maemopad
 X-Window-Icon-Dimmed=maemopad
 X-Osso-Service=com.nokia.maemopad
 X-Osso-Type=application/x-executable

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

 # Service description file
 [D-BUS Service]
 Name=com.nokia.maemopad
 Exec=/usr/bin/maemopad

These files reside on the device here:

* <code>/usr/share/applications/hildon</code>
* <code>/usr/share/dbus-1/services</code>

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

== Packaging the application ==

{{main|Packaging}}

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 the [[Documentation/Maemo 5 Developer Guide/Packaging%2C Deploying and Distributing#Creating Debian Packages|creating Debian packages]] section of the [[Documentation/Maemo 5 Developer Guide/Packaging, Deploying and Distributing|Packaging, Deploying and Distributing chapter]]. 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, be sure that the package is in an [[Documentation/Maemo 5 Developer Guide/Packaging%2C Deploying and Distributing#Sections|allowed section]].

=== Creating debian/ Directory ===

In order to create the package, the following files are created in the <code>debian/</code> directory:

* <code>changelog</code>
* <code>control</code>
* <code>copyright</code>
* <code>rules</code>
* ... etc ...

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

Most important lines in rules file are:

<source lang="bash">
# Add here commands to install the package into debian/<installation directory>
$(MAKE) install DESTDIR=$(CURDIR)/debian/<installation directory>
</source>

These lines define where the package files are installed. <code>debian/<installation directory></code> 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:

* <code>maemopad_x.x.dsc</code>
* <code>maemopad_x.x.tar.gz</code>
* <code>maemopad_x.x_i386.changes</code>
* <code>maemopad_x.x_i386.deb</code>

A .deb file now exists. This package can be installed using:
 fakeroot dpkg -i maemopad_x.x_i386.deb
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

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