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

m (Added link to GNU Build System page.)
(I removed font tag from example code)
 
(20 intermediate revisions not shown)
Line 1: Line 1:
-
= 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.  
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.  
-
<nowiki> A simple text editor with a few essential features is used as a example. Let us name it as ''MaemoPad'' </nowiki>.
+
A simple text editor with a few essential features is used as a example. Let us name it as ''MaemoPad''.
-
<nowiki> 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. </nowiki>
+
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.
The figure below is a screenshot of the text editor.
-
[[Image:Maemopad2.png|500px]]
+
[[Image:Maemopad2.png|500px|alt=Screenshot of MaemoPad|MaemoPad text editor]]
-
= Creating the application file structure =
+
== Creating the application file structure ==
-
In general, a maemo application uses [[../../GNU_Build_System|GNU Build System]] and has the following files and subdirectories:
+
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>src/</code>: Contains the source files.
-
* <code>debian/</code>: Contains the files related to debian packaging
+
* <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>data/</code>: Contains all data files needed to run the application. Maemopad will need the following data files:
-
**<code>.desktop</code> file  
+
**<code>maemopad.desktop</code> file  
-
**D-Bus <code>.service</code> file  
+
**D-Bus <code>maemopad.service</code> file  
**application icons in a separate directory called <code>icons/</code>
**application icons in a separate directory called <code>icons/</code>
* <code>po/</code>: Contains the localization files. Maemopad contains the following files:
* <code>po/</code>: Contains the localization files. Maemopad contains the following files:
Line 26: Line 24:
* <code>autogen.sh</code> is a shell script that provides automatic build system preparation.
* <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>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/, po/ and data/</code> and all the <code>Makefile</code>s in <code>src/, po/, and data/</code> directories.
+
* <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:
You can compile the source as follows:
Line 34: Line 32:
   [sbox-FREMANTLE_X86 ~] >$ make
   [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.
-
For more information about GNU autoconf and automake, see chapter [http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/GNU_Build_System GNU build system]
+
== Coding the application ==
-
 
+
-
= Coding the application =
+
The src/ directory of MaemoPad contains the following files:
The src/ directory of MaemoPad contains the following files:
Line 47: Line 44:
* Makefile.am
* Makefile.am
-
== maemopad-window.h ==
+
=== 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:
<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:
-
typedef struct _MaemopadWindow MaemopadWindow;
+
<source lang="c">
-
+
typedef struct _MaemopadWindow MaemopadWindow;
-
struct _MaemopadWindow
+
 
-
{
+
struct _MaemopadWindow
 +
{
   HildonWindow parent;
   HildonWindow parent;
-
 
+
 
-
   <font color=red>/* Osso context, needed for "send via" functionality. */</font>
+
   /* Osso context, needed for "send via" functionality. */
   osso_context_t *osso;  
   osso_context_t *osso;  
-
 
+
 
-
   <font color=red>/* Fullscreen mode is on (TRUE) or off (FALSE): */</font>
+
   /* Fullscreen mode is on (TRUE) or off (FALSE): */
   gboolean fullscreen;
   gboolean fullscreen;
-
 
+
 
-
   <font color=red>/* Button items for menu: */</font>
+
   /* Button items for menu: */
   GtkWidget *new_item;
   GtkWidget *new_item;
   GtkWidget *open_item;
   GtkWidget *open_item;
Line 71: Line 69:
   GtkWidget *copy_item;
   GtkWidget *copy_item;
   GtkWidget *paste_item;
   GtkWidget *paste_item;
-
   <font color=red>/*.....more...truncated...*/</font>
+
   /*.....more...truncated...*/
-
};
+
};
 +
</source>
-
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.
+
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 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.
+
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 AppData variable as global.
+
Many applications declare this <code>AppData</code> variable as global.
-
== main.c ==
+
=== main.c ===
main.c usually performs, at least, the following functions:
main.c usually performs, at least, the following functions:
-
* Initializing GTK
+
* Initializing GTK+
* Initializing localization
* Initializing localization
-
* Creating an instance of HildonProgram
+
* Creating an instance of <code>HildonProgram</code>
-
* Calling to a function, usually defined in interface.c, to create the main view.
+
* Calling to a function, usually defined in <code>interface.c</code>, to create the main view.
-
* Connecting the main view window to the created HildonProgram
+
* Connecting the main view window to the created <code>HildonProgram</code>
* Running <code>gtk_main()</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.
+
* 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>
* Call <code>gtk_main_quit()</code>
Here is the main function of MaemoPad with comments:
Here is the main function of MaemoPad with comments:
-
int main (int argc, char* argv[])
+
<source lang="c">
-
{
+
int main (int argc, char* argv[])
 +
{
   osso_context_t *osso = NULL;
   osso_context_t *osso = NULL;
   AppData *data = g_new0 (AppData, 1);
   AppData *data = g_new0 (AppData, 1);
   
   
-
   <font color=red>/* Initialize the locale stuff: */</font>
+
   /* Initialize the locale stuff: */
   setlocale (LC_ALL, "");
   setlocale (LC_ALL, "");
   bindtextdomain (GETTEXT_PACKAGE, LOCALEDIR);
   bindtextdomain (GETTEXT_PACKAGE, LOCALEDIR);
Line 106: Line 106:
   textdomain (GETTEXT_PACKAGE);
   textdomain (GETTEXT_PACKAGE);
   
   
-
   <font color=red>/* Inititialize GTK+ and hildon: */</font>
+
   /* Inititialize GTK+ and hildon: */
   hildon_gtk_init (&argc, &argv);
   hildon_gtk_init (&argc, &argv);
   
   
Line 113: Line 113:
   }
   }
   
   
-
   <font color=red>/* Create the hildon application and setup the title: */</font>
+
   /* Create the hildon application and setup the title: */
   data->program = HILDON_PROGRAM (hildon_program_get_instance ());
   data->program = HILDON_PROGRAM (hildon_program_get_instance ());
   g_set_application_name (_("MaemoPad"));
   g_set_application_name (_("MaemoPad"));
   
   
-
   <font color=red>/* We need the osso context to call libmodest_dbus_client_compose_mail() later. */</font>
+
   /* We need the osso context to call libmodest_dbus_client_compose_mail() later. */
   osso = osso_initialize (OSSO_SERVICE, VERSION, TRUE, NULL);
   osso = osso_initialize (OSSO_SERVICE, VERSION, TRUE, NULL);
   g_assert (osso);
   g_assert (osso);
   
   
-
   <font color=red>/* Create the window for our application: */</font>
+
   /* Create the window for our application: */
   data->window = maemopad_window_new (osso);
   data->window = maemopad_window_new (osso);
   hildon_program_add_window (data->program, data->window);
   hildon_program_add_window (data->program, data->window);
   
   
-
   <font color=red>/* Show the main window and start the mainloop,  
+
   /* Show the main window and start the mainloop,  
   * quitting the mainloop when it the main window is hidden:
   * quitting the mainloop when it the main window is hidden:
-
   */</font>
+
   */
   gtk_widget_show (GTK_WIDGET (data->window));
   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, "hide", G_CALLBACK (&on_main_window_hide), NULL);
Line 134: Line 134:
   gtk_main();
   gtk_main();
    
    
-
   <font color=red>/* Clean up: */</font>
+
   /* Clean up: */
   gtk_widget_destroy (GTK_WIDGET (data->window));
   gtk_widget_destroy (GTK_WIDGET (data->window));
   g_free (data);
   g_free (data);
   
   
   return 0;
   return 0;
-
}
+
}
 +
</source>
-
= User interface =
+
== User interface ==
-
The graphical user interface code is implemented in directory '''./src/ui/'''. It contains two .c files: interface.c and callbacks.c
+
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 ==
+
=== 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 [localhost#sec:writing_maemo_gui_applications [[Image:crossref.png|[*]]]] for information on how to create GUI in Maemo. For more information on GTK see the GTK+ Reference Manual [[/node22.html#maemoapi 52]].
+
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 AppUIData struct variable is created when creating the GUI. And then, a HildonWindow and smaller components are created in different functions, such as <code>create_menu()</code>, <code>create_toolbar()</code>. When creating each component, AppUIData should refer various necessary UI objects created along the way.
+
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.
-
<nowiki> The following excerpt shows how AppUIData is created, and how it points to the toolbar and the button ``New file'' on the toolbar. </nowiki>
+
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.
-
<tt><span>''<span><font color="#9A1900">/* Creates and initializes a main_view */</font></span>''</span>
+
<source lang="c">
-
AppUIData<span><font color="#990000"><nowiki>*</nowiki></font></span> <span>'''<span><font color="#000000">interface_main_view_new</font></span>'''</span><span><font color="#990000">(</font></span> AppData <span><font color="#990000"><nowiki>*</nowiki></font></span>data <span><font color="#990000">)</font></span>
+
/* Creates and initializes a main_view */
-
<span><font color="#FF0000">{</font></span>
+
AppUIData* interface_main_view_new( AppData *data )
-
    <span>''<span><font color="#9A1900">/* Zero memory with g_new0 */</font></span>''</span>
+
{
-
    AppUIData<span><font color="#990000"><nowiki>*</nowiki></font></span> result <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">g_new0</font></span>'''</span><span><font color="#990000">(</font></span> AppUIData<span><font color="#990000">,</font></span> <span><font color="#993399">1</font></span> <span><font color="#990000">);</font></span>
+
    /* Zero memory with g_new0 */
-
    <span>''<span><font color="#9A1900">/*....*/</font></span>''</span>
+
    AppUIData* result = g_new0( AppUIData, 1 );
-
    <span>'''<span><font color="#000000">create_toolbar</font></span>'''</span><span><font color="#990000">(</font></span> result <span><font color="#990000">);</font></span>
+
    /*....*/
-
    <span>''<span><font color="#9A1900">/*....*/</font></span>''</span>
+
    create_toolbar( result );
-
<span><font color="#FF0000">}</font></span>
+
    /*....*/
-
<span>''<span><font color="#9A1900">/* Create toolbar to mainview */</font></span>''</span>
+
}
-
<span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">create_toolbar</font></span>'''</span> <span><font color="#990000">(</font></span> AppUIData <span><font color="#990000"><nowiki>*</nowiki></font></span>main <span><font color="#990000">)</font></span>
+
/* Create toolbar to mainview */
-
<span><font color="#FF0000">{</font></span>
+
static void create_toolbar ( AppUIData *main )
-
    <span>''<span><font color="#9A1900">/* Create new GTK toolbar */</font></span>''</span>
+
{
-
    main<span><font color="#990000">-&gt;</font></span>toolbar <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_toolbar_new</font></span>'''</span> <span><font color="#990000">();</font></span>
+
    /* Create new GTK toolbar */
-
    <span>''<span><font color="#9A1900">/*....*/</font></span>''</span>
+
    main->toolbar = gtk_toolbar_new ();
-
    <span>''<span><font color="#9A1900">/* Create the "New file" button in the toolbar */</font></span>''</span>
+
    /*....*/
-
    main<span><font color="#990000">-&gt;</font></span>new_tb <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_tool_button_new_from_stock</font></span>'''</span><span><font color="#990000">(</font></span>GTK_STOCK_NEW<span><font color="#990000">);</font></span>
+
    /* Create the "New file" button in the toolbar */
-
    <span>''<span><font color="#9A1900">/*....*/</font></span>''</span>
+
    main->new_tb = gtk_tool_button_new_from_stock(GTK_STOCK_NEW);
-
<span><font color="#FF0000">}</font></span>
+
    /*....*/
-
</tt>
+
}
 +
</source>
-
== callbacks.c ==
+
=== 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.
+
<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.
-
<tt><span>''<span><font color="#9A1900">/* Create the menu items needed for the drop down menu */</font></span>''</span>
+
<source lang="c">
-
<span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">create_menu</font></span>'''</span><span><font color="#990000">(</font></span> AppUIData <span><font color="#990000"><nowiki>*</nowiki></font></span>main <span><font color="#990000">)</font></span>
+
/* Create the menu items needed for the drop down menu */
-
<span><font color="#FF0000">{</font></span>
+
static void create_menu( AppUIData *main )
-
    <span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
{
-
    main<span><font color="#990000">-&gt;</font></span>new_item <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_menu_item_new_with_label</font></span>'''</span> <span><font color="#990000">(</font></span> <span>'''<span><font color="#000000">_</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"New"</font></span><span><font color="#990000">)</font></span> <span><font color="#990000">);</font></span>
+
    /* ... */
-
    <span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
    main->new_item = gtk_menu_item_new_with_label ( _("New") );
-
    <span>''<span><font color="#9A1900">/* Attach the callback functions to the activate signal */</font></span>''</span>
+
    /* ... */
-
    <span>'''<span><font color="#000000">g_signal_connect</font></span>'''</span><span><font color="#990000">(</font></span> <span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span><span><font color="#990000">(</font></span> main<span><font color="#990000">-&gt;</font></span>new_item <span><font color="#990000">),</font></span> <span><font color="#FF0000">"activate"</font></span><span><font color="#990000">,</font></span>
+
    /* Attach the callback functions to the activate signal */
-
                      <span>'''<span><font color="#000000">G_CALLBACK</font></span>'''</span> <span><font color="#990000">(</font></span> callback_file_new<span><font color="#990000">),</font></span> main <span><font color="#990000">);</font></span>
+
    g_signal_connect( G_OBJECT( main->new_item ), "activate",
-
    <span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
                      G_CALLBACK ( callback_file_new), main );
-
<span><font color="#FF0000">}</font></span></tt>
+
    /* ... */
 +
}
 +
</source>
-
Function callback_file_new is implemented in callbacks.c, saving the current file if needed, and then opening a new file to edit.
+
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.
-
<tt><span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">callback_file_new</font></span>'''</span><span><font color="#990000">(</font></span>GtkAction <span><font color="#990000"><nowiki>*</nowiki></font></span> action<span><font color="#990000">,</font></span> gpointer data<span><font color="#990000">)</font></span>
+
<source lang="c">
-
<span><font color="#FF0000">{</font></span>
+
void callback_file_new(GtkAction * action, gpointer data)
-
    gint answer<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
{
-
    AppUIData <span><font color="#990000"><nowiki>*</nowiki></font></span>mainview <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
    gint answer;
-
    mainview <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#990000">(</font></span> AppUIData <span><font color="#990000"><nowiki>*</nowiki></font></span> <span><font color="#990000">)</font></span> data<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
    AppUIData *mainview = NULL;
-
    <span>'''<span><font color="#000000">g_assert</font></span>'''</span><span><font color="#990000">(</font></span>mainview <span><font color="#990000"><nowiki>!=</nowiki></font></span> NULL <span><font color="#990000">&amp;&amp;</font></span> mainview<span><font color="#990000">-&gt;</font></span>data <span><font color="#990000"><nowiki>!=</nowiki></font></span> NULL <span><font color="#990000">);</font></span>
+
    mainview = ( AppUIData * ) data;
-
    <span>''<span><font color="#9A1900">/* save changes note if file is edited */</font></span>''</span>
+
    g_assert(mainview != NULL && mainview->data != NULL );
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span><span><font color="#990000">(</font></span> mainview<span><font color="#990000">-&gt;</font></span>file_edited <span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+
    /* save changes note if file is edited */
-
        answer <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">interface_save_changes_note</font></span>'''</span><span><font color="#990000">(</font></span> mainview <span><font color="#990000">);</font></span>
+
    if( mainview->file_edited ) {
-
        <span>'''<span><font color="#0000FF">if</font></span>'''</span><span><font color="#990000">(</font></span> answer <span><font color="#990000"><nowiki>==</nowiki></font></span> CONFRESP_YES <span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+
        answer = interface_save_changes_note( mainview );
-
            <span>'''<span><font color="#0000FF">if</font></span>'''</span><span><font color="#990000">(</font></span> mainview<span><font color="#990000">-&gt;</font></span>file_name <span><font color="#990000"><nowiki>==</nowiki></font></span> NULL <span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+
        if( answer == CONFRESP_YES ) {
-
                mainview<span><font color="#990000">-&gt;</font></span>file_name <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">interface_file_chooser</font></span>'''</span><span><font color="#990000">(</font></span>mainview<span><font color="#990000">,</font></span> GTK_FILE_CHOOSER_ACTION_SAVE<span><font color="#990000">);</font></span>
+
            if( mainview->file_name == NULL ) {
-
            <span><font color="#FF0000">}</font></span>
+
                mainview->file_name = interface_file_chooser(mainview, GTK_FILE_CHOOSER_ACTION_SAVE);
-
            <span>'''<span><font color="#000000">write_buffer_to_file</font></span>'''</span> <span><font color="#990000">(</font></span> mainview <span><font color="#990000">);</font></span>
+
            }
-
        <span><font color="#FF0000">}</font></span>
+
            write_buffer_to_file ( mainview );
-
    <span><font color="#FF0000">}</font></span>
+
        }
-
    <span>''<span><font color="#9A1900">/* clear buffer, filename and free buffer text */</font></span>''</span>
+
    }
-
    <span>'''<span><font color="#000000">gtk_text_buffer_set_text</font></span>'''</span> <span><font color="#990000">(</font></span> <span>'''<span><font color="#000000">GTK_TEXT_BUFFER</font></span>'''</span> <span><font color="#990000">(</font></span>mainview<span><font color="#990000">-&gt;</font></span>buffer<span><font color="#990000">),</font></span> <span><font color="#FF0000">""</font></span><span><font color="#990000">,</font></span> <span><font color="#990000">-</font></span><span><font color="#993399">1</font></span> <span><font color="#990000">);</font></span>
+
    /* clear buffer, filename and free buffer text */
-
    mainview<span><font color="#990000">-&gt;</font></span>file_name <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
    gtk_text_buffer_set_text ( GTK_TEXT_BUFFER (mainview->buffer), "", -1 );
-
    mainview<span><font color="#990000">-&gt;</font></span>file_edited <span><font color="#990000"><nowiki>=</nowiki></font></span> FALSE<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
    mainview->file_name = NULL;
-
<span><font color="#FF0000">}</font></span></tt>
+
    mainview->file_edited = FALSE;
 +
}
 +
</source>
-
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.
+
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:
MaemoPad contains many functions:
-
* File Save/Save-As/Open: This uses HildonFileChooserDialog.
+
* File Save/Save-As/Open: This uses <code>HildonFileChooserDialog</code>.
-
* Edit Cut/Copy/Paste: This uses Clipboard ([/node13.html#sec:clipboard_usage 12.2])
+
* Edit Cut/Copy/Paste: This uses the clipboard ([[Documentation/Maemo 5 Developer Guide/Using Data Sharing/Clipboard Usage|clipboard usage]])
-
* 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 <code>HildonFontSelectionDialog</code> and <code>HildonColorChooser</code>.
-
* Font/Color Selector: These are explained in HildonFontSelectionDialog and HildonColorChooser.
+
* [[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]]
-
* Send via Email/Bluetooth: Refer to section ''<nowiki>``Send via'' functionality</nowiki>'' [/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 [http://maemo.org/api_refs/4.0/gtk/GtkWidget.html GTK+ Reference Manual].
+
=== interface.h ===
-
== 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:
-
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:
+
<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>
-
<tt><span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> MAIN_VIEW_NAME <span><font color="#FF0000">"AppUIData"</font></span>
+
== Localization ==
-
<span>'''<span><font color="#0000FF">typedef</font></span>'''</span> <span>'''<span><font color="#0000FF">enum</font></span>'''</span> <span><font color="#FF0000">{</font></span>
+
-
    MAEMOPAD_NO_ERROR <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#993399">0</font></span><span><font color="#990000">,</font></span>
+
-
    MAEMOPAD_ERROR_INVALID_URI<span><font color="#990000">,</font></span>
+
-
    MAEMOPAD_ERROR_SAVE_FAILED<span><font color="#990000">,</font></span>
+
-
    MAEMOPAD_ERROR_OPEN_FAILED
+
-
<span><font color="#FF0000">}</font></span> MaemopadError<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span>''<span><font color="#9A1900">/* Struct to include view's information */</font></span>''</span>
+
-
<span>'''<span><font color="#0000FF">typedef</font></span>'''</span> <span>'''<span><font color="#0000FF">struct</font></span>'''</span> <span><font color="#009900">_AppUIData</font></span> AppUIData<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span>'''<span><font color="#0000FF">struct</font></span>'''</span> <span><font color="#009900">_AppUIData</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
    <span>''<span><font color="#9A1900">/* Handle to app's data */</font></span>''</span>
+
-
    AppData <span><font color="#990000"><nowiki>*</nowiki></font></span>data<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span>''<span><font color="#9A1900">/* Fullscreen mode is on (TRUE) or off (FALSE) */</font></span>''</span>
+
-
    gboolean fullscreen<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span>''<span><font color="#9A1900">/* Items for menu */</font></span>''</span>
+
-
    GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>file_item<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>new_item<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
-
    GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>font_item<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>fullscreen_item<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span>''<span><font color="#9A1900">/* Toolbar */</font></span>''</span>
+
-
    GtkWidget<span><font color="#990000"><nowiki>*</nowiki></font></span> toolbar<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    GtkWidget<span><font color="#990000"><nowiki>*</nowiki></font></span> iconw<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    GtkToolItem<span><font color="#990000"><nowiki>*</nowiki></font></span> new_tb<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    GtkToolItem<span><font color="#990000"><nowiki>*</nowiki></font></span> open_tb<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
-
    <span>''<span><font color="#9A1900">/* Textview related */</font></span>''</span>
+
-
    GtkWidget<span><font color="#990000"><nowiki>*</nowiki></font></span> scrolledwindow<span><font color="#990000"><nowiki>;</nowiki></font></span>  <span>''<span><font color="#9A1900">/* textview is under this widget */</font></span>''</span>
+
-
    GtkWidget<span><font color="#990000"><nowiki>*</nowiki></font></span> textview<span><font color="#990000"><nowiki>;</nowiki></font></span>        <span>''<span><font color="#9A1900">/* widget that shows the text */</font></span>''</span>
+
-
    GtkTextBuffer<span><font color="#990000"><nowiki>*</nowiki></font></span> buffer<span><font color="#990000"><nowiki>;</nowiki></font></span>      <span>''<span><font color="#9A1900">/* buffer that contains the text */</font></span>''</span>
+
-
    GtkClipboard<span><font color="#990000"><nowiki>*</nowiki></font></span> clipboard<span><font color="#990000"><nowiki>;</nowiki></font></span>    <span>''<span><font color="#9A1900">/* clipboard for copy/paste */</font></span>''</span>
+
-
    PangoFontDescription<span><font color="#990000"><nowiki>*</nowiki></font></span> font_desc<span><font color="#990000"><nowiki>;</nowiki></font></span>    <span>''<span><font color="#9A1900">/* font used in textview */</font></span>''</span>
+
-
    gboolean file_edited<span><font color="#990000"><nowiki>;</nowiki></font></span>    <span>''<span><font color="#9A1900">/* tells is our file on view edited */</font></span>''</span>
+
-
    gchar<span><font color="#990000"><nowiki>*</nowiki></font></span> file_name<span><font color="#990000"><nowiki>;</nowiki></font></span>        <span>''<span><font color="#9A1900">/* directory/file under editing */</font></span>''</span>
+
-
<span><font color="#FF0000">}</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span>''<span><font color="#9A1900">/* Public functions: */</font></span>''</span>
+
-
AppUIData<span><font color="#990000"><nowiki>*</nowiki></font></span> <span>'''<span><font color="#000000">interface_main_view_new</font></span>'''</span><span><font color="#990000">(</font></span> AppData<span><font color="#990000"><nowiki>*</nowiki></font></span> data <span><font color="#990000">);</font></span>
+
-
<span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">interface_main_view_destroy</font></span>'''</span><span><font color="#990000">(</font></span> AppUIData<span><font color="#990000"><nowiki>*</nowiki></font></span> main <span><font color="#990000">);</font></span>
+
-
<span><font color="#009900">char</font></span><span><font color="#990000"><nowiki>*</nowiki></font></span> <span>'''<span><font color="#000000">interface_file_chooser</font></span>'''</span><span><font color="#990000">(</font></span> AppUIData<span><font color="#990000"><nowiki>*</nowiki></font></span> main<span><font color="#990000">,</font></span> GtkFileChooserAction action <span><font color="#990000">);</font></span>
+
-
PangoFontDescription<span><font color="#990000"><nowiki>*</nowiki></font></span> <span>'''<span><font color="#000000">interface_font_chooser</font></span>'''</span><span><font color="#990000">(</font></span> AppUIData <span><font color="#990000"><nowiki>*</nowiki></font></span> main <span><font color="#990000">);</font></span>
+
-
<span>''<span><font color="#9A1900">/* ... */</font></span>''</span></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 <code>gettext()</code>.
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 ==
+
===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:
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:
-
<tt><span><font color="#009900">int</font></span> <span>'''<span><font color="#000000">main</font></span>'''</span><span><font color="#990000">(</font></span> <span><font color="#009900">int</font></span> argc<span><font color="#990000">,</font></span> <span><font color="#009900">char</font></span><span><font color="#990000"><nowiki>*</nowiki></font></span> argv<span><font color="#990000">[]</font></span> <span><font color="#990000">)</font></span>
+
<source lang="c">
-
<span><font color="#FF0000">{</font></span>
+
int main( int argc, char* argv[] )
-
    <span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
{
-
    <span>''<span><font color="#9A1900">/* Initialize the locale stuff */</font></span>''</span>
+
    /* ... */
-
    <span>'''<span><font color="#000000">setlocale</font></span>'''</span> <span><font color="#990000">(</font></span> LC_ALL<span><font color="#990000">,</font></span> <span><font color="#FF0000">""</font></span> <span><font color="#990000">);</font></span>
+
    /* Initialize the locale stuff */
-
    <span>'''<span><font color="#000000">bindtextdomain</font></span>'''</span> <span><font color="#990000">(</font></span> GETTEXT_PACKAGE<span><font color="#990000">,</font></span> LOCALEDIR <span><font color="#990000">);</font></span>
+
    setlocale ( LC_ALL, "" );
-
    <span>'''<span><font color="#000000">bind_textdomain_codeset</font></span>'''</span><span><font color="#990000">(</font></span>GETTEXT_PACKAGE<span><font color="#990000">,</font></span> <span><font color="#FF0000">"UTF-8"</font></span><span><font color="#990000">);</font></span>
+
    bindtextdomain ( GETTEXT_PACKAGE, LOCALEDIR );
-
    <span>'''<span><font color="#000000">textdomain</font></span>'''</span> <span><font color="#990000">(</font></span> GETTEXT_PACKAGE <span><font color="#990000">);</font></span>
+
    bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
-
    <span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
    textdomain ( GETTEXT_PACKAGE );
-
<span><font color="#FF0000">}</font></span></tt>
+
    /* ... */
 +
}
 +
</source>
-
More information on localization can be found in section [/node17.html#sec:maemo_localization 16.4].
+
More information on localization can be found in the [[Documentation/Maemo 5 Developer Guide/Application Development/Maemo Localization|Maemo localization]] section.
-
== File structure ==
+
=== File structure ===
-
Localization files are stored in the po/ directory. The following files are used for MaemoPad localization:
+
Localization files are stored in the <code>po/</code> directory. The following files are used for MaemoPad localization:
-
Makefile.am
+
* <code>Makefile.am</code>
-
POTFILES.in
+
* <code>POTFILES.in</code>
-
en_GB.po
+
* <code>en_GB.po</code>
-
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.
+
<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.
-
  <tt><span>''<span><font color="#9A1900"><nowiki># List of MaemoPad source files to be localized</nowiki></font></span>''</span>
+
  # List of MaemoPad source files to be localized
-
  <span><font color="#990000">..</font></span>/src/main<span><font color="#990000">.</font></span>c
+
  ../src/main.c
-
  <span><font color="#990000">..</font></span>/src/ui/interface<span><font color="#990000">.</font></span>c</tt>
+
  ../src/ui/interface.c
-
File en_GB.po includes translated text for British English. It contains pairs of id/string as follows:
+
File <code>en_GB.po</code> includes translated text for British English. It contains pairs of id/string as follows:
-
  <tt><span>''<span><font color="#9A1900"><nowiki># ...</nowiki></font></span>''</span>
+
  # ...
-
  msgid <span><font color="#FF0000">"maemopad_yes"</font></span>
+
  msgid "maemopad_yes"
-
  msgstr <span><font color="#FF0000">"Yes"</font></span>
+
  msgstr "Yes"
-
  <span>''<span><font color="#9A1900"><nowiki># ...</nowiki></font></span>''</span></tt>
+
  # ...
'''N.B.''' The comments in .po file start with ``#``.
'''N.B.''' The comments in .po file start with ``#``.
-
== Using en_GB.po ==
+
=== 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
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
-
<tt><span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> <span>'''<span><font color="#000000">_</font></span>'''</span><span><font color="#990000">(</font></span>String<span><font color="#990000">)</font></span> <span>'''<span><font color="#000000">gettext</font></span>'''</span><span><font color="#990000">(</font></span>String<span><font color="#990000">)</font></span></tt>
+
<source lang="c">
 +
#define _(String) gettext(String)
 +
</source>
Therefore, in MaemoPad, the string for Menu-&gt;File-&gt;Open menu is created as follows:
Therefore, in MaemoPad, the string for Menu-&gt;File-&gt;Open menu is created as follows:
-
<tt>    main<span><font color="#990000">-&gt;</font></span>open_item <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_menu_item_new_with_label</font></span>'''</span> <span><font color="#990000">(</font></span> <span>'''<span><font color="#000000">_</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Open"</font></span><span><font color="#990000">)</font></span> <span><font color="#990000">);</font></span></tt>
+
<source lang="c">
 +
main->open_item = gtk_menu_item_new_with_label ( _("Open") );
 +
</source>
-
=== 8.8.5.4 Creating .po files from 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 template.po file
+
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
  xgettext -f POTFILES.in -C -a -o template.po
Line 335: Line 346:
Read the man page for xgettext for more information, in short:
Read the man page for xgettext for more information, in short:
-
* ``-f POTFILES.in`` uses POTFILES.in to get the files to be localized
+
* <code>-f POTFILES.in</code> uses <code>POTFILES.in</code> to get the files to be localized
-
* ``-C`` is for C-code type of strings
+
* <code>-C</code> is for C-code type of strings
-
* ``-a`` is for ensuring that we get all strings from specified files
+
* <code>-a</code> is for ensuring that we get all strings from specified files
-
* ``-o template.po`` defines the output filename.
+
* <code>-o template.po</code> 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.
+
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 =
+
== 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
+
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:
-
  <code>[Desktop Entry]
+
  [Desktop Entry]
  Encoding=UTF-8
  Encoding=UTF-8
  Version=0.1
  Version=0.1
Line 356: Line 367:
  X-Window-Icon-Dimmed=maemopad
  X-Window-Icon-Dimmed=maemopad
  X-Osso-Service=com.nokia.maemopad
  X-Osso-Service=com.nokia.maemopad
-
  X-Osso-Type=application/x-executable</code>
+
  X-Osso-Type=application/x-executable
('''N.B.''' Whitespace is not allowed after the lines.)
('''N.B.''' Whitespace is not allowed after the lines.)
-
  <code><nowiki># Service description file
+
  # Service description file
  [D-BUS Service]
  [D-BUS Service]
  Name=com.nokia.maemopad
  Name=com.nokia.maemopad
-
  Exec=/usr/bin/maemopad</nowiki></code>
+
  Exec=/usr/bin/maemopad
These files reside on the device here:
These files reside on the device here:
-
/usr/share/applications/hildon
+
* <code>/usr/share/applications/hildon</code>
-
/usr/share/dbus-1/services
+
* <code>/usr/share/dbus-1/services</code>
-
 
+
-
= 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.
When the Debian package is installed to Maemo platform, .desktop and .service files are used to link MaemoPad to the Task Navigator.
-
== Adding help =
+
== Packaging the application ==
-
 
+
-
Applications can have their own help files. Help files are XML files located under the <code>/usr/share/osso-help</code> directory. Each language is located in its own subdirectory, such as <code>/usr/share/osso-help/en_GB</code> for British English help files. MaemoPad has <code>data/help/en_GB/MaemoPad.xml</code> with very simple help content. The middle part of the contextUID must be the same as the help file name (without suffix):
+
-
 
+
-
<tt><span>'''<span><font color="#000080">&lt;?xml</font></span>'''</span> <span><font color="#009900">version</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"1.0"</font></span> <span><font color="#009900">encoding</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"UTF-8"</font></span><span>'''<span><font color="#000080">?&gt;</font></span>'''</span>
+
-
<span>'''<span><font color="#0000FF">&lt;hildonhelpsource&gt;</font></span>'''</span>
+
-
  <span>'''<span><font color="#0000FF">&lt;folder&gt;</font></span>'''</span>
+
-
    <span>'''<span><font color="#0000FF">&lt;title&gt;</font></span>'''</span>MaemoPad<span>'''<span><font color="#0000FF">&lt;/title&gt;</font></span>'''</span>
+
-
    <span>'''<span><font color="#0000FF">&lt;topic&gt;</font></span>'''</span>
+
-
      <span>'''<span><font color="#0000FF">&lt;topictitle&gt;</font></span>'''</span>Main Topic<span>'''<span><font color="#0000FF">&lt;/topictitle&gt;</font></span>'''</span>
+
-
      <span>'''<span><font color="#0000FF">&lt;context</font></span>'''</span> <span><font color="#009900">contextUID</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"Example_MaemoPad_Content"</font></span> <span>'''<span><font color="#0000FF">/&gt;</font></span>'''</span>
+
-
      <span>'''<span><font color="#0000FF">&lt;para&gt;</font></span>'''</span>This is a help file with example content.<span>'''<span><font color="#0000FF">&lt;/para&gt;</font></span>'''</span>
+
-
    <span>'''<span><font color="#0000FF">&lt;/topic&gt;</font></span>'''</span>
+
-
  <span>'''<span><font color="#0000FF">&lt;/folder&gt;</font></span>'''</span>
+
-
<span>'''<span><font color="#0000FF">&lt;/hildonhelpsource&gt;</font></span>'''</span>
+
-
</tt>
+
-
 
+
-
By using <code>hildon_help_show()</code> 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><span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">callback_help</font></span>'''</span><span><font color="#990000">(</font></span> GtkAction <span><font color="#990000"><nowiki>*</nowiki></font></span> action<span><font color="#990000">,</font></span> gpointer data <span><font color="#990000">)</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
    osso_return_t retval<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span>''<span><font color="#9A1900">/* connect pointer to our AppUIData struct */</font></span>''</span>
+
-
    AppUIData <span><font color="#990000"><nowiki>*</nowiki></font></span>mainview <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    mainview <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#990000">(</font></span> AppUIData <span><font color="#990000"><nowiki>*</nowiki></font></span> <span><font color="#990000">)</font></span> data<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span>'''<span><font color="#000000">g_assert</font></span>'''</span><span><font color="#990000">(</font></span>mainview <span><font color="#990000"><nowiki>!=</nowiki></font></span> NULL <span><font color="#990000">&amp;&amp;</font></span> mainview<span><font color="#990000">-&gt;</font></span>data <span><font color="#990000"><nowiki>!=</nowiki></font></span> NULL <span><font color="#990000">);</font></span>
+
-
    retval <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_help_show</font></span>'''</span><span><font color="#990000">(</font></span>
+
-
      mainview<span><font color="#990000">-&gt;</font></span>data<span><font color="#990000">-&gt;</font></span>osso<span><font color="#990000">,</font></span> <span>''<span><font color="#9A1900">/* osso_context */</font></span>''</span>
+
-
      HELP_TOPIC_ID<span><font color="#990000">,</font></span>        <span>''<span><font color="#9A1900">/* topic id */</font></span>''</span>
+
-
      HILDON_HELP_SHOW_DIALOG<span><font color="#990000">);</font></span>
+
-
<span><font color="#FF0000">}</font></span></tt>
+
-
= 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 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.
+
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, see section ''Making application packages'' [/node18.html#sec:making_app_pack 17.2] of the same aforementioned chapter.
+
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 ==
+
=== Creating debian/ Directory ===
-
In order to create the package, the following files are created in the debian/ directory:
+
In order to create the package, the following files are created in the <code>debian/</code> directory:
-
changelog
+
* <code>changelog</code>
-
control
+
* <code>control</code>
-
copyright
+
* <code>copyright</code>
-
rules
+
* <code>rules</code>
-
... etc ...
+
* ... 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.
+
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:
Most important lines in rules file are:
-
<tt><span>''<span><font color="#9A1900"><nowiki># Add here commands to install the package into debian/&lt;installation directory&gt;</nowiki></font></span>''</span>
+
<source lang="bash">
-
<span><font color="#009900">$(MAKE)</font></span> install <span><font color="#009900">DESTDIR</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#009900">$(CURDIR)</font></span>/debian<span><font color="#990000">/&lt;</font></span>installation directory<span><font color="#990000">&gt;</font></span></tt>
+
# 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. debian/&lt;installation directory&gt; is used as a temporary directory for package construction.
+
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 ==
+
=== Creating and building the package ===
The package is made using the following command:
The package is made using the following command:
Line 444: Line 425:
* <code>maemopad_x.x_i386.deb</code>
* <code>maemopad_x.x_i386.deb</code>
-
<nowiki> 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''. </nowiki>
+
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:Development]]
[[Category:Documentation]]
[[Category:Documentation]]
[[Category:Fremantle]]
[[Category:Fremantle]]

Latest revision as of 08:43, 14 May 2011

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.

Screenshot of MaemoPad

Contents

[edit] Creating the application file structure

In general, a Maemo application uses the GNU Build System and has the following files and subdirectories:

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

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

[edit] maemopad-window.h

maemopad-window.h defines the MaemopadWindow 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.

[edit] 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 gtk_main()
  • Connecting the delete_event 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 gtk_main_quit()

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;
}

[edit] User interface

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

[edit] interface.c

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

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 create_menu(), create_toolbar(). When creating each component, AppUIData should refer to 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 );
    /*....*/
    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);
    /*....*/
}

[edit] 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.

/* 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 );
    /* ... */
}

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

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;
}

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 the clipboard (clipboard usage)
  • Font/Color Selector: These are explained in HildonFontSelectionDialog and HildonColorChooser.
  • Send via Email/Bluetooth

[edit] 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:

#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 );
/* ... */

[edit] 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 gettext().

[edit] Initialization

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

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 );
    /* ... */
}

More information on localization can be found in the Maemo localization section.

[edit] 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.

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

File en_GB.po 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 ``#``.

[edit] Using en_GB.po

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

#define _(String) gettext(String)

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

main->open_item = gtk_menu_item_new_with_label ( _("Open") );

[edit] 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.

[edit] Adding application to menu

In short, the maemopad.desktop and com.nokia.maemopad.service files are stored in the ./data 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:

  • /usr/share/applications/hildon
  • /usr/share/dbus-1/services

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

[edit] Packaging the application

Main article: 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 creating Debian packages section of the 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 allowed section.

[edit] 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:

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

These lines define where the package files are installed. debian/<installation directory> is used as a temporary directory for package construction.

[edit] 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:

  • maemopad_x.x.dsc
  • maemopad_x.x.tar.gz
  • maemopad_x.x_i386.changes
  • maemopad_x.x_i386.deb

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