Editing Documentation/Maemo 5 Developer Guide/Porting Software/Redesigning From Maemo 4 to Maemo 5

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

Warning: This page is 31 kilobytes long; some browsers may have problems editing pages approaching or longer than 32kb. Please consider breaking the page into smaller sections.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

= Redesigning From Maemo 4 to Maemo 5 =

This chapter instructs how to re-design a Maemo 4 application to Maemo 5, i.e. the '''Hildon 2.2 UI Style'''. The Modest email client is used as the example application.

== Overall Guidelines ==
Compared to Maemo 4, the Hildon 2.2 UI Style in Maemo 5 is much more optimized for finger usage in small mobile device displays.

When the focus in design moves from stylus oriented user interface (UI) to finger optimized user interface, the reduction of the amount of visible elements in the UI becomes first priority. This means that unlike typical desktop applications, most of the functionality is not provided in a single view, but instead there are more views and each view is optimized for a single use case only. This is similar to the UNIX philosophy – “''do one thing and do it well''".

The major changes in the Hildon 2.2 UI Style include larger size for UI elements, removal of focus (particularly in lists), no dimming of buttons, limit of 10 items in view menus, removal of tabs in dialogs and lesser importance of toolbars and context sensitive menus.

=== Larger size of UI elements ===
By default, the UI elements in Maemo 5 should be designed as “Finger size”. This means that on average, a view can contain fewer visible UI elements. To compensate this, views and dialogs can be designed to support panning, allowing for larger amount of UI elements in total. However, panning is not an ideal design solution for all use cases.

=== Removal of focus ===
While in Maemo 4, the application menu and the toolbars often relied on focused/selected item or items as the target of a command, in Maemo 5 there is no focus. This also means that keyboard navigation is not supported in the UI in general.

In Maemo 5, the design should follow one of two possible UI flows:
* User navigates multiple views from a list or a grid of items to a view with single item. Commands that operate on that single item can be provided in that last view (typically via View menu or Toolbar)
* After user has activated a command, a separate item selection view is used (typically Edit Mode view)

=== No dimming ===
Instead of dimming (buttons, menu items ...), the UI elements should be simply hidden away, when they are not active. There are some corner cases where hiding would break the UI flow. For example Edit mode view toolbar simply shows the action button as always active, even though nothing happens, when nothing is selected, if the button is pressed.

=== Limit of 10 items in the view menus ===
The Maemo 4 application menu typically contains most or the full set of functionality of the application, organized in hierarchical menus.
In Maemo 5, there is a strict limit of maximum 10 items in a view menu, and there is no menu hierarchy.

The Maemo 5 View menus are not application menus, in the sense that a view menu only contains commands relevant to that particular view. The only exception to this is the Root view menu, which additionally contains menu item(s) for application settings.

=== Removal of tabs in dialogs ===
When designing dialogs in Maemo 5, the tabs of a Maemo 4 dialog are merged to a single tab-less dialog with the whole content area of the dialog being pannable. In practice this results in user panning the dialog instead of switching between tabs.

If additional semantic grouping is needed for UI elements within the dialog, then group titles can be used by utilizing <code>GtkFrame</code>.

=== Fewer toolbars and context sensitive menus ===
With the removal of focus from default lists and grids, the UI designs for Maemo 5 typically do not include toolbars for views that contain multiple items. Toolbars are still used in views where only a single item is being shown.

The main use cases for context sensitive menus in Maemo 5 are only:
* To show commands that operate on a single list/grid item
* To show commands related to an item inside content, for example a web link.
Note that the context sensitive menus should only include commands that are not available elsewhere in the user interface.

== Re-design of Modest email ==
The following paragraphs describe the overall changes made to the Modest email client when re-designing it from Maemo 4 to Maemo 5.

=== Task views ===
In Maemo 4, Modest had three views: Main view, Viewer view and Editor view.
In Maemo 5, the Main view was divided into more focused views, which allowed to get rid of the split view as well. The new five views are: Accounts view, Folders view, Messages view, Viewer view and Editor view.

[[Image:Modest-ui-flow.png|Modest UI Flow]]<br>
''Figure 1: Email UI Flow in Maemo 4 and Maemo 5''

While in Maemo 4 the different views are separate windows (and visible as such when switching between tasks), in Maemo 5 the views are designed as a “stack”, i.e. only one of the views is ever visible at any one time.

The Maemo 5 approach allows the design to avoid many concurrency problems caused by changes happening in several windows at the same time. On the other hand the design forces the views to be always closable. This means for example that in Maemo 5, the Editor view always automatically saves as draft, without further confirmation, when that view is closed.

The UI flow of Modest in Maemo 5 follows the “drilling down” UI flow – Initially the most generic view is shown (Accounts) from which more detailed views can be reached (ending up in Viewer). The Editor view is not directly part of this flow, but instead can be accessed from any of the other views. Going

back from Editor view shows the previous view of the “stack”, i.e. the view from which the user opened the Editor view.

==== Accounts view ====
The design of this view is simply to list the accounts use has set up on the device. Tapping on any of the accounts opens Folders view of that account. In addition to the account name, also the time stamp of the last account refresh is shown on each list item.
<br>
The first item in the list is “New message” button, which is a convenience shortcut to quick write a new email in the Editor view.<br>
[[Image:H22-Modest-Accounts-view.png|Accounts view|300px]]
<br><br>

==== Folders view ====
This view lists folders related to the selected email account. Additionally also ''Local folders'' (stored on the device), and ''Archive'' (stored on external memory card if available) are shown in the list.
<br>
The folder tree in Maemo 4 was a direct representation of the physical folder structure. In Maemo 5 the fingerable lists are flat and pannable, and expandable lists are not supported. These constraints required re-designing how subfolders are represented in the UI. A full-blown design of each-subfolder-is-a-subview was too navigation heavy approach for email application, and instead all folders and subfolders are shown in the same pannable list.
<br><br>
The depth of a folder is indicated by the amount of dots (<code>&amp;middot;</code>) placed before the name of the folder.
<br><br>
The icon in each list item represents the location of the storage (email server, local, MMC), except for the standard email folders, which have individual icons (Inbox, Drafts, Outbox, Sent).
<br><br>
If a folder contains new, unread messages then this status is indicated with <code>ActiveTextColor</code> on the folder name and with informative text on the right half of the list item.<br>
[[Image:H22-Modest-Folders-view.png|Folders view|300px]]
<br><br>

==== Messages view ====
The messages view in Maemo 5 has very few changes compared to Maemo 4. The most visible changes are 1) indicating the unread status with <code>ActiveTextColor</code> and 2) the “New message” shortcut button.<br>
[[Image:H22-Modest-Messages-view.png|Messages view|300px]]
<br><br>

==== Viewer view ====
The main changes in the viewer view has been to remove all less important UI elements either to view menu or to the toolbar – the subject is shown in view title, the message header only contains From, Date and Attachment fields. This design allows to maximize the screen space for the most important content (the email message itself), while giving direct access to most used actions in the toolbar.
<table width="100%"><tr>
<td style="vertical-align: top; width: 320px">[[Image:Diablo-Modest_viewer_view.png|Diablo Viewer view|300px]]
</td><td style="padding-left:20px; vertical-align: top;">[[Image:H22-Modest-Viewer-view.png|Viewer view|300px]]
</td></tr></table>

<br>

==== Editor view ====
The basic layout and logic of the Editor view remains unchanged. However, due to increasing the UI elements to finger size, following tweaks were made to this view:
* “Send” button was moved to the right side of “from” picker button, in order to reserve the toolbar only for message formatting commands
* Addressbook buttons were merged with the To, CC and BCC field titles to save screen space and increase usability – ''tapping directly on the content''. Also, CC and BCC fields are now hidden by default.
* Attachment button was moved to View menu, also to save screen space.
<table width="100%"><tr>
<td style="vertical-align: top; width: 320px">[[Image:Diablo-Modest_editor_view.png|Diablo Editor view|300px]]
</td><td style="padding-left:20px; vertical-align: top;">[[Image:H22-Modest-Editor-view.png|Editor view|300px]]
</td></tr></table>

<br>

=== Commands ===
The following tables compare the commands in the Maemo 4 and Maemo 5 versions of the Modest email client.

The Maemo 4 duplicated most of the commands between Application menu, Toolbar and Context sensitive menu.

<br>
{|border="2" cellspacing="0" cellpadding="4" width="80%"
|bgcolor = "#D9D9D9"|'''Location'''
|bgcolor = "#D9D9D9"|'''Menu commands in Maemo 5 Modest'''

|-
|Accounts view menu
|'''New account, Edit accounts, SMTP servers''', Send & receive / Stop sending, '''Settings'''

|-
|Folders view menu
|'''New folder, Rename folder, Move folder, Delete folder''', Send &amp; receive/stop sending, Edit account

|-
|Messages view menu
|'''New message, Move messages, Delete messages''', Folder details, Sort, Send &amp; receive/stop sending

|-
|Viewer view menu
|Find in message, Move message, Forward, Mark as read, Mark as unread, Save attachments, Remove attachments, New message, Add to Contacts, Message details

|-
|Editor view menu
|Check names, Undo, Show/Hide CC, Show/Hide BCC, Insert image, Add attachment, Remove attachments, Message settings, Find in message

|}
<br>
Notable changes are:
* In general, commands are specific to their view
* Accounts view menu is the main and only access point to application settings
* Edit mode view (for selecting items) are opened from: Rename folder, Move folder, Delete folder, move messages, delete messages
* Viewer and Editor menus only contain commands which are not available in the view’s toolbar.
* Additional, view specific, settings dialog is opened from “Message settings” in Editor menu. That dialog contains settings for message priority (high, normal, low) and message format (plain text, formatted text). The settings only apply to the currently edited message.
* New message command only appears in Messages and Viewer view menus, as access to that command is provided by quick access button in Accounts view, Folders view (the first item in the list)

<br>
{|border="2" cellspacing="0" cellpadding="4" width="80%"
|bgcolor = "#D9D9D9"|'''Location'''
|bgcolor = "#D9D9D9"|'''Toolbar commands in Maemo 5 Modest'''

|-
|Viewer view toolbar
|Reply, Reply all, delete, load external images, previous message, next message

|-
|Editor view toolbar
|Font face, Font size, Bold, Italics, Font color

|}
<br>
Notable changes are:
* The Accounts, Folders and Messages views do not have toolbar, since they contain a list without focus. This also allows maximizing the amount of rows visible.
* The commands in toolbars are not repeated elsewhere in the UI.

<br>
{|border="2" cellspacing="0" cellpadding="4" width="80%"
|bgcolor = "#D9D9D9"|'''Location'''
|bgcolor = "#D9D9D9"|'''context sensitive commands in Maemo 5 Modest'''

|-
|Messages view context sensitive menu
|Delete, mark unread/read

|}
<br>
Notable changes are:
* Almost all the context sensitive menus were removed. Only the most important commands (targetting a single message) were included to the Messages view context sensitive menu.

=== Dialogs ===
There are very many dialogs in the email application, mostly due to the complexity of the email handling in general. This chapter uses the Account settings dialog as the example of changes in dialogs.

The most visible change in the Account Settings dialog is that the tabs used in Maemo 4 were removed and instead in Maemo 5, all the settings in the dialog are reachable with panning.

The conversion of the widgets themselves for Maemo 5 was quite straightforward – all the buttons, input fields, checkboxes et cetera were simply changed to their fingerable Hildon 2.2 versions.

Notable other changes are:
* The signature button was moved to the dialog button area, since the settings in the dialog content are more related to email server connectivity.
* The account deletion is included in the Account Settings dialog directly, as the account list dialog does not have focus.

<table width="100%"><tr>
<td style="vertical-align: top; width: 320px">[[Image:Diablo-modest-account-settings.png|Diablo account settings|300px]]
</td><td style="padding-left:20px; vertical-align: top;">[[Image:H22-Modest-account-settings.png|Modest account settings|300px]]
</td></tr></table>

== Porting MaemoPad ==

This is a practical example of porting a Diablo (Maemo 4.1) application to Fremantle (Maemo 5). The example application, MaemoPad, is a simple Notepad-like editor.

{| summary="MaemoPad"
|+ align="BOTTOM" |'''Figure:''' MaemoPad
|-
|
<div align="CENTER">[[Image:maemopad.png|Image maemopad]]</div>
|}

</div>

Porting from Diablo to Fremantle involved mostly changes in GTK+- and Hildon-specific parts of the code, because newer versions of these libraries are now in use, and because of the new Fremantle GUI guidelines. This subsection will first explain how to install MaemoPad, and then proceeds to describing the main changes in the code. The reader is recommended to familiarize with chapters Application Development[/node7.html#chap:application_dev [[Image:crossref.png|[*]]]] and Hildon Human Interface Guidelines[/node12.html#chap:Hildon_Human_Interface_Guidelines [[Image:crossref.png|[*]]]] before this one. For reference, see GTK+ and Hildon APIs from [http://maemo.org/development/sdks/maemo_5_api_documentation/ Maemo Fremantle APIs].

=== Installing MaemoPad ===

MaemoPad can be installed and tested in the scratchbox environment.

* If not already activated, activate the X86 target, go to the testing directory, and download the source package of maemopad application.
 
 [sbox-FREMANTLE_ARMEL] sb-conf select FREMANTLE_X86
 [sbox-FREMANTLE_X86 ~] mkdir maemopad
 [sbox-FREMANTLE_X86 ~/maemopad] cd maemopad
 [sbox-FREMANTLE_X86 ~/maemopad] apt-get source maemopad
 ...apt output...

* Check that you have the correct files.
 
 [sbox-FREMANTLE_X86: ~/maemopad] &gt; ls -l
 total 352
 drwxrwxr-x  6 maemo maemo   4096 Jul 28 14:09 maemopad-2.5
 -rw-rw-r--  1 maemo maemo    465 Jul  6 16:02 maemopad_2.5.dsc
 -rw-rw-r--  1 maemo maemo 346129 Jul  6 16:02 maemopad_2.5.tar.gz

* Go to the <code>maemopad-2.5</code> source directory, and build the maemopad package with <code>dpkg-buildpackage</code> command as shown here:
 
 [sbox-FREMANTLE_X86: ~/maemopad] &gt; cd maemopad-2.5
 [sbox-FREMANTLE_X86: ~/maemopad/maemopad-2.5] &gt; dpkg-buildpackage -rfakeroot
 dpkg-buildpackage: source package is maemopad
 dpkg-buildpackage: source version is 2.5
 dpkg-buildpackage: source changed by Soumya Bijjal &lt;soumya.3.bijjal@nokia.com&gt;
 dpkg-buildpackage: host architecture i386
 dpkg-buildpackage: source version without epoch 2.3
 .... etc ....

* Install the newly compiled <code>maemopad_2.5_i386.deb</code> file inside the Scratchbox environment:
 
 [sbox-FREMANTLE_X86: ~/maemopad] &gt; dpkg -i maemopad_2.5_i386.deb
 ... output from dpkg ...

* Make sure you have the SDK UI running in Xephyr.
* You can now run MaemoPad by selecting it from the menu.

The MaemoPad source code resides in folder <code>maemopad-2.5/src:</code>

[sbox-FREMANTLE_X86: ~/maemopad] ls maemopad-2.5/src
 total 280
 -rw-rw-r--  1 maemo maemo 25491 Jul 28 15:45 Makefile
 -rw-rw-r--  1 maemo maemo   491 Jul 28 14:09 Makefile.am
 -rw-rw-r--  1 maemo maemo 23238 Jul 28 14:09 Makefile.in
 -rwxrwxr-x  1 maemo maemo 83433 Jul 28 15:45 maemopad
 -rw-rw-r--  1 maemo maemo 82928 Jul 28 15:45 maemopad-maemopad-window.o
 -rw-rw-r--  1 maemo maemo 18564 Jul 28 15:45 maemopad-main.o
 -rw-rw-r--  1 maemo maemo 20400 Jul 28 14:09 maemopad-window.c
 -rw-rw-r--  1 maemo maemo  2391 Jul 28 14:09 maemopad-window.h
 -rw-rw-r--  1 maemo maemo  2193 Jul 28 14:09 main.c

For comparison, the Diablo version of MaemoPad can also be examined:

[sbox-FREMANTLE_X86: ~/maemopad] &gt; svn export https://garage.maemo.org/svn/\
 maemoexamples/tags/maemo_4.1/maemopad diablo_maemopad
 [sbox-FREMANTLE_X86: ~/src] ls -lR diablo_maemopad/src
 diablo_maemopad/src/:
 total 16
 -rw-rw-r--  1 maemo maemo  537 May 15  2008 Makefile.am
 -rw-rw-r--  1 maemo maemo  557 May 15  2008 appdata.h
 -rw-rw-r--  1 maemo maemo 2789 Dec  3  2008 main.c
 drwxrwxr-x  2 maemo maemo 4096 Aug 20 11:53 ui
 
 diablo_maemopad/src/ui:
 total 36
 -rw-rw-r--  1 maemo maemo 12163 Dec  3  2008 callbacks.c
 -rw-rw-r--  1 maemo maemo  1682 Oct 29  2008 callbacks.h
 -rw-rw-r--  1 maemo maemo 14982 Dec  3  2008 interface.c
 -rw-rw-r--  1 maemo maemo  2695 Dec  3  2008 interface.h

=== Code reorganization ===

If one takes a look at MaemoPad source code for Diablo and Fremantle, there are many bug fixes, and there have been major refractorizations. These are, however, not necessary for porting and are not discussed here in detail. The main change is reorganizing the files, which is already apparent from the <code>ls</code> lists above:

* <code>src/ui</code> subfolder has been dropped
* <code>src/ui/callbacks.c</code> and <code>src/ui/interface</code> have been combined into <code>src/maemopad-window.c</code>, similarly for header files
* <code>appdata.h</code> is included in <code>main.c</code>
* In <code>src/Makefile.am</code>, <code>maemopad_SOURCES = &lt;list of source files&gt;</code> has been updated correspondingly.

=== Device-specific changes ===

The previous device, N810, had a separate full-screen and ESC keys that were dropped from the new device. In MaemoPad, pressing the full-screen key was replaced by Ctrl-F. This required the following addition

* maemopad-window.c

#include <gdk/gdkkeysyms.h>

to include GDK definition for key "f", <code>GDK_f</code> to replace the earlier <code>HILDON_HARDKEY_FULLSCREEN</code>. Callback for Esc was completely removed. The full-screen action itself was principally unchanged. The key event function was modified correspondingly:

* Diablo callbacks.c

gboolean key_press(GtkWidget * widget, GdkEventKey * event,
                      gpointer data)
 {
     ...
     if (event->keyval == HILDON_HARDKEY_FULLSCREEN && !keypressed){
         keypressed = TRUE;
     ...
     if (event->keyval == HILDON_HARDKEY_ESC && !keypressed){
         keypressed = TRUE;
     ...

* Fremantle maemopad-window.c

static gboolean maemopad_window_on_key_press(GtkWidget *widget, GdkEventKey *event,
                      gpointer data)
 {
     ... 
     if (event->keyval == GDK_f && (event->state & GDK_CONTROL_MASK) && !self- >key_pressed) {
         self->key_pressed = TRUE;
     ...

=== Dropped libraries ===

Hildon help library, libhildonhelp, was dropped from Fremantle so all dependencies to it had to be removed.

libhildonhelp-dev needs to removed from build depencies:

Diablo: debian/control:

Build-Depends: debhelper (&gt;= 4.0.0), intltool,
  libhildon1-dev, libgtk2.0-dev, libosso-gnomevfs2-dev,
  libglib2.0-dev, libdbus-glib-1-dev, libosso-dev, libmodest-dbus-client-dev,
  conbtdialogs-dev,libhildonhelp-dev, libhildonfm2-dev, osso-af-settings

Fremantle: debian/control:

Callback and all other help stuff removed:

* Diablo callbacks.c

/* help */
 void callback_help( GtkAction * action, gpointer data )
 {
     osso_return_t retval;
     /* connect pointer to our AppUIData struct */
     AppUIData *mainview = NULL;
     mainview = ( AppUIData * ) data;
     g_assert(mainview != NULL && mainview->data != NULL );
     retval = hildon_help_show(
       mainview->data->osso, /* osso_context */
       HELP_TOPIC_ID,        /* topic id */
       HILDON_HELP_SHOW_DIALOG);
 }

* Diablo interface.c

GtkWidget *help = NULL;
 help = gtk_menu_item_new_with_label( _("Help") );
 gtk_menu_append( main_menu, help );
 g_signal_connect( G_OBJECT( help ), "activate", 
 G_CALLBACK ( callback_help ), main );

* Diablo callbacks.c

#include <hildon/hildon-help.h>
 #define HELP_TOPIC_ID "Example_MaemoPad_Content"

* Diablo configure.ac:

PKG_CHECK_MODULES(HILDON, hildon-1 hildon-fm-2 hildon-help conbtdialogs)

* Fremantle configure.ac:
 
 PKG_CHECK_MODULES(HILDON, hildon-1 hildon-fm-2 conbtdialogs)

Removed data/help directory which contained an example help file.

Some files contained items related to it and they were also removed:

* Diablo data/Makefile.am:
 
 helpfile_engb_DATA = help/en_GB/MaemoPad.xml
 -EXTRA_DIST = $(serviceentry_DATA) $(desktopentry_DATA) $(icon_26x26_DATA) $(icon_40x40_DATA)
 $(icon_scalable_DATA) *$(helpfile_engb_DATA)*

Diablo data/Makefile.am:

<nowiki>
 # Help file install directory
 helpfile_engbdir=$datadir/hildon-help/en_GB
 AC_SUBST(helpfile_engbdir) NOT YET
 </nowiki>

=== GUI design changes ===

Because of new UI guidelines, a toolbar that was at the bottom of the MaemoPadwindow in Diablo was dropped. This meant removing the function <code>create_toolbar</code> from <code>interface.c</code>, line 282 and its declaration on line 47 of the same file. Also the call for the function was dropped from the same file. Likewise, related declarations were dropped:

* interface.h

/* Toolbar */
 GtkWidget* toolbar;
 GtkWidget* iconw;
 GtkToolItem* new_tb;
 GtkToolItem* open_tb;
 ...
 GtkToolItem* fullscreen_tb;

Also the menu system was changed. In Diablo, a GtkMenu was used, but it was replaced with a HildonAppMenu in Fremantle, shown in Figure [localhost#fig:maemopad_menu [[Image:crossref.png|[*]]]].

{| summary="MaemoPad Menu"
|+ align="BOTTOM" |'''Figure:''' MaemoPad Menu
|-
|
<div align="CENTER">[[Image:maemopad_menu.png|Image maemopad_menu]]</div>
|}

</div>

Function <code>create_menu()</code> is responsible for creating the menus in both versions:

* Diablo interface.c

static void create_menu( AppUIData *main )
 {
     /* Create needed handles */
     GtkMenu *main_menu;
     GtkWidget *file_menu, *edit_menu, *sendvia_menu;
     GtkWidget *separator = NULL;
     GtkWidget *close = NULL;
     /* Create main menu and new menus for submenus in our drop down menu */
     main_menu = GTK_MENU( gtk_menu_new () );
     file_menu = gtk_menu_new ();
     edit_menu = gtk_menu_new ();
     sendvia_menu = gtk_menu_new ();
     /* Create the menu items */
     main->file_item = gtk_menu_item_new_with_label ( _("File") );
     main->new_item = gtk_menu_item_new_with_label ( _("New") );
     main->open_item = gtk_menu_item_new_with_label ( _("Open") );
     ...
     /* Add menu items to right menus */
     gtk_menu_append( main_menu, main->file_item );
     gtk_menu_append( file_menu, main->new_item );
     gtk_menu_append( file_menu, main->open_item );
     ...
     gtk_menu_append( main_menu, close );
     /* Add submenus to the right items */
     gtk_menu_item_set_submenu( GTK_MENU_ITEM (main->file_item), file_menu );
     gtk_menu_item_set_submenu( GTK_MENU_ITEM (main->edit_item), edit_menu );
     gtk_menu_item_set_submenu( GTK_MENU_ITEM (main->sendvia_item),   sendvia_menu );
     /* Attach the callback functions to the activate signal */
     g_signal_connect( G_OBJECT( main->new_item ), "activate", 
 		      G_CALLBACK ( callback_file_new), main );
     g_signal_connect( G_OBJECT( main->open_item ), "activate", 
 		      G_CALLBACK ( callback_file_open), main );
     ...
     g_signal_connect( G_OBJECT( close ), "activate", gtk_main_quit, NULL );
     /* Add menu to HildonWindow */
     hildon_window_set_menu(main->data->window, main_menu);
     /* We need to show menu items */
     gtk_widget_show_all( GTK_WIDGET( main_menu ) );
 }

* Fremantle maemopad-window.c

static GtkWidget* add_menu_item (GtkWidget *main_menu, const gchar* title,
     GCallback clicked_callback, gpointer user_data)
 {
   HildonAppMenu *app_menu = HILDON_APP_MENU (main_menu);
   /* Create a button, add it, and return it: */ 
   GtkWidget *button = hildon_button_new_with_text (HILDON_SIZE_AUTO, 
         HILDON_BUTTON_ARRANGEMENT_VERTICAL, title, NULL);
   gtk_widget_show (button);
   g_signal_connect_after (button, "clicked", 
   	G_CALLBACK (clicked_callback), user_data);
   hildon_app_menu_append (app_menu, GTK_BUTTON (button));
   return button;
 }
 /* Create the menu items needed: */
 static void create_menu (MaemopadWindow *self)
 {
   /* Create needed handles */
   GtkWidget *main_menu = hildon_app_menu_new ();
   /* Create the menu items */
   self->new_item = add_menu_item (main_menu, _("New"),
     G_CALLBACK (&maemopad_window_on_menu_file_new), self);
   self->open_item = add_menu_item (main_menu, _("Open"),
     G_CALLBACK (&maemopad_window_on_menu_file_open), self);
   ...
    self->close_item = add_menu_item (main_menu, _("Close"),
     G_CALLBACK (&maemopad_window_on_menu_close), self);
   /* Add menu to HildonWindow */
   hildon_window_set_app_menu (
     HILDON_WINDOW (self),
     HILDON_APP_MENU (main_menu));
   /* We need to show menu items */
   gtk_widget_show_all (GTK_WIDGET (main_menu));
 }

As a result to changes in the .c file, the following menu widget declarations used in Diablo became unnecessary:

* interface.h

GtkWidget *file_item;
 GtkWidget *edit_item;
 GtkWidget *sendvia_item;

Menu callbacks were also changed. There were some changes in the callbacks themselves as a result of code reorganizations, but the main change from the menu viewpoint was that the 1st arguments of the callbacks were changed from GtkAction to GtkButton, like in the following example.

* Diablo callbacks.c

void callback_file_new(GtkAction * action, gpointer data)

* Fremantle maemopad-window.c

static void maemopad_window_on_menu_file_new (GtkButton *button, gpointer data)

=== Other updates in GTK+ and Hildon ===

* Rich text support was changed with the new GTK+, as described in [http://live.gnome.org/Maemo/Gtk210Migration Maemo-GTK+ 2.6 to 2.10 Migration].This required editing two lines: <br />Part of function create_textarea() in Diablo interface.c

/* Enable Rich Text Support */
 gtk_text_buffer_set_can_paste_rich_text ( main->buffer, TRUE );
 gtk_text_buffer_set_rich_text_format ( main->buffer, "RTF" );

Part of function create_textarea() in Fremantle maemopad-window.c

/* Enable Rich Text Support */
 gtk_text_buffer_register_serialize_tagset (self->buffer, "RTF");
 gtk_text_buffer_register_deserialize_tagset (self->buffer, "RTF");

* HildonFontSelectionDialog was deprecated and replaced with a GtkFontButton.
In Diablo, the font callback was a callback to a regular GtkAction:

callback.c

void callback_font( GtkAction * action, gpointer data )
 {
     ...
     new_font = interface_font_chooser( mainview );
     /* if we got a new font from chooser -> change font */
     if( new_font != NULL ) {
         mainview->font_desc = new_font;
         gtk_widget_modify_font ( mainview->textview, mainview->font_desc );
     }
 }

Function <code>callback_font</code> got the font from an auxiliary function <code>interface_font_chooser()</code> and then modified the font in the text view. The auxiliary function <code>interface_font_chooser()</code> in turn opened a HildonFontSelectionDialog that returned the font parameters:
callback.c

/* Font chooser */
 PangoFontDescription* interface_font_chooser( AppUIData * main )
 {
     ...
     font = pango_font_description_new();
     /* create dialog */
     dialog = HILDON_FONT_SELECTION_DIALOG ( hildon_font_selection_dialog_new( NULL, NULL ) );
     gtk_widget_show_all (GTK_WIDGET(dialog));
     if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_OK)
     {
         g_object_get(G_OBJECT(dialog),
                     "family", &family,
                     "size", &size,
                     "bold", &bold,
                     "italic", &italic,
                     NULL);
         pango_font_description_set_family(font, family);
         pango_font_description_set_size(font, size * PANGO_SCALE);
         if (bold) {
             pango_font_description_set_weight(font, PANGO_WEIGHT_BOLD);
         } else {
             pango_font_description_set_weight(font, PANGO_WEIGHT_NORMAL);
         }
         if (italic) {
             pango_font_description_set_style(font, PANGO_STYLE_ITALIC);
         } else {
             pango_font_description_set_style(font, PANGO_STYLE_NORMAL);
         }
     }
     gtk_widget_destroy(GTK_WIDGET(dialog));
     return font;
 }

Instead of the deprecated HildonFontSelectionDialog, Fremantle uses a GtkFontButton directly in the font button callback:

* maemopad-window.c

/* font */
 static void maemopad_window_on_font_set (GtkFontButton *button, gpointer data)
 {
   ...
   font_name = gtk_font_button_get_font_name (button);
   if (!font_name)
     return;
   new_font = pango_font_description_from_string (font_name);
   /* Change the font used in the GtkTextView */
   if (new_font) {
     if (self->font_desc)
       pango_font_description_free (self->font_desc);
      self->font_desc = new_font;
      gtk_widget_modify_font (self->textview, self->font_desc);
   }
 }

This GtkFontButton was initialized in function <code>create_menu()</code> (see above) in maemopad-window.c so that it would respond to the <code>"font-set"</code> signal and call the callback above:

self->font_item = gtk_font_button_new ();
  gtk_widget_show (self->font_item);
  g_signal_connect_after (self->font_item, "font-set", 
    G_CALLBACK (maemopad_window_on_font_set), self);
  hildon_app_menu_append (HILDON_APP_MENU (main_menu), GTK_BUTTON (self->font_item));

* Instead of GtkTextView, a [http://maemo.org/api_refs/5.0/beta/hildon/HildonTextView.html HildonTextView] is now used.

* Diablo callback.c

/* Create the text area */
 void create_textarea( AppUIData *main )
 {
     /* Text view */
     main->textview = gtk_text_view_new ();
     ...
     /* Get handle */
     main->buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (main->textview));
     ...
 }

* Fremantle maemopad-window.c

static void create_textarea (MaemopadWindow *self)
 {
     /* Text view */
     self->textview = hildon_text_view_new ();
     ....
     /* Get handle */
     self->buffer = hildon_text_view_get_buffer (GTK_TEXT_VIEW (self->textview));
 }

* All Hildon applications should now initialize hildon before using it. In maemopad this is done by calling <code>hildon_gtk_init()</code> which also calls <code>gtk_init()</code> so the original call can be removed:
Diablo main.c 
 /* Init the gtk - must be called before any hildon stuff */
 gtk_init( &argc, &argv );
Fremantle main.c 
 /* Inititialize GTK+ and hildon: */
 hildon_gtk_init( &argc, &argv );

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Retrieved from "http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Porting_Software/Redesigning_From_Maemo_4_to_Maemo_5"

Personal tools

Navigation

Views

Editing Documentation/Maemo 5 Developer Guide/Porting Software/Redesigning From Maemo 4 to Maemo 5

@@ Line 1: / Line 1: @@
-This chapter instructs how to re-design a [[Open development/Maemo roadmap/Diablo|Maemo 4]] application to [[Open development/Maemo roadmap/Diablo|Maemo 5]], i.e. the '''Hildon 2.2 UI Style'''. The Modest email client is used as the example application.
+= Redesigning From Maemo 4 to Maemo 5 =
-This document is supported by the [http://www.forum.nokia.com/info/sw.nokia.com/id/e778ba1f-2507-4672-be45-798359a3aea7/Fremantle_Master_Layout_Guide.html Fremantle Master Layout Guide] and [http://www.forum.nokia.com/info/sw.nokia.com/id/eb8a68ba-6225-4d84-ba8f-a00e4a05ff6f/Hildon_2_2_UI_Style_Guide.html Hildon 2.2 UI Style Guide] for visual guidance and references, as well as by the [http://www.forum.nokia.com/info/sw.nokia.com/id/019c2b31-3777-49a0-9257-970d79580756/Hildon_2_2_Widget_UI_Specification.html Hildon 2.2 Widget UI Specification] for interaction and technical background information.
+This chapter instructs how to re-design a Maemo 4 application to Maemo 5, i.e. the '''Hildon 2.2 UI Style'''. The Modest email client is used as the example application.
-== Overall Guidelines ==
+== Overall Guidelines ==
 Compared to Maemo 4, the Hildon 2.2 UI Style in Maemo 5 is much more optimized for finger usage in small mobile device displays.
@@ Line 11: / Line 11: @@
 The major changes in the Hildon 2.2 UI Style include larger size for UI elements, removal of focus (particularly in lists), no dimming of buttons, limit of 10 items in view menus, removal of tabs in dialogs and lesser importance of toolbars and context sensitive menus.
-=== Larger size of UI elements ===
+=== Larger size of UI elements ===
 By default, the UI elements in Maemo 5 should be designed as “Finger size”. This means that on average, a view can contain fewer visible UI elements. To compensate this, views and dialogs can be designed to support panning, allowing for larger amount of UI elements in total. However, panning is not an ideal design solution for all use cases.
-=== Removal of focus ===
+=== Removal of focus ===
 While in Maemo 4, the application menu and the toolbars often relied on focused/selected item or items as the target of a command, in Maemo 5 there is no focus. This also means that keyboard navigation is not supported in the UI in general.
@@ Line 23: / Line 23: @@
 * After user has activated a command, a separate item selection view is used (typically Edit Mode view)
-=== No dimming ===
+=== No dimming ===
 Instead of dimming (buttons, menu items ...), the UI elements should be simply hidden away, when they are not active. There are some corner cases where hiding would break the UI flow. For example Edit mode view toolbar simply shows the action button as always active, even though nothing happens, when nothing is selected, if the button is pressed.
 === Limit of 10 items in the view menus ===
+The Maemo 4 application menu typically contains most or the full set of functionality of the application, organized in hierarchical menus.
-The Maemo 4 application menu typically contains most or the full set of functionality of the application, organized in hierarchical menus. In Maemo 5, there is a strict limit of maximum 10 items in a view menu, and there is no menu hierarchy.
+In Maemo 5, there is a strict limit of maximum 10 items in a view menu, and there is no menu hierarchy.
 The Maemo 5 View menus are not application menus, in the sense that a view menu only contains commands relevant to that particular view. The only exception to this is the Root view menu, which additionally contains menu item(s) for application settings.
 === Removal of tabs in dialogs ===
+When designing dialogs in Maemo 5, the tabs of a Maemo 4 dialog are merged to a single tab-less dialog with the whole content area of the dialog being pannable. In practice this results in user panning the dialog instead of switching between tabs.
-When designing dialogs in Maemo 5, the tabs of a Maemo 4 dialog are merged to a single tab-less dialog with the whole content area of the dialog being pannable. In practice this results in the user panning the dialog instead of switching between tabs.
 If additional semantic grouping is needed for UI elements within the dialog, then group titles can be used by utilizing <code>GtkFrame</code>.
-=== Fewer toolbars and context sensitive menus ===
+=== Fewer toolbars and context sensitive menus ===
 With the removal of focus from default lists and grids, the UI designs for Maemo 5 typically do not include toolbars for views that contain multiple items. Toolbars are still used in views where only a single item is being shown.
@@ Line 47: / Line 48: @@
 * To show commands related to an item inside content, for example a web link.
 Note that the context sensitive menus should only include commands that are not available elsewhere in the user interface.
 == Re-design of Modest email ==
 The following paragraphs describe the overall changes made to the Modest email client when re-designing it from Maemo 4 to Maemo 5.
 === Task views ===
 In Maemo 4, Modest had three views: Main view, Viewer view and Editor view.
 In Maemo 5, the Main view was divided into more focused views, which allowed to get rid of the split view as well. The new five views are: Accounts view, Folders view, Messages view, Viewer view and Editor view.
-[[Image:Modest-ui-flow.png|Modest UI Flow|frame|center|alt=Collage of Maemo 4 and Maemo 5 Email UI|Email UI Flow in Maemo 4 and 5]]
-While in Maemo 4 the different views are separate windows (and visible as such when switching between tasks), in Maemo 5 the views are designed as a “stack”, i.e. only one of the views is ever visible at any one time.
+[[Image:Modest-ui-flow.png|Modest UI Flow]]<br>
+''Figure 1: Email UI Flow in Maemo 4 and Maemo 5''
-The Maemo 5 approach allows the design to avoid many concurrency problems caused by changes happening in several windows at the same time. On the other hand the design forces the views to always be closable. This means for example that in Maemo 5, the Editor view always automatically saves as draft, without further confirmation, when that view is closed.
-The UI flow of Modest in Maemo 5 follows the “drilling down” UI flow – Initially the most generic view is shown (Accounts) from which more detailed views can be reached (ending up in Viewer). The Editor view is not directly part of this flow, but instead can be accessed from any of the other views. Going back from the Editor view shows the previous view of the “stack”, i.e. the view from which the user opened the Editor view.
+While in Maemo 4 the different views are separate windows (and visible as such when switching between tasks), in Maemo 5 the views are designed as a “stack”, i.e. only one of the views is ever visible at any one time.
-==== Accounts view ====
+The Maemo 5 approach allows the design to avoid many concurrency problems caused by changes happening in several windows at the same time. On the other hand the design forces the views to be always closable. This means for example that in Maemo 5, the Editor view always automatically saves as draft, without further confirmation, when that view is closed.
-The design of this view is simply to list the accounts that the user has set up on the device. Tapping on any of the accounts opens the Folders view of that account. In addition to the account name, also the time stamp of the last account refresh is shown on each list item.
+The UI flow of Modest in Maemo 5 follows the “drilling down” UI flow – Initially the most generic view is shown (Accounts) from which more detailed views can be reached (ending up in Viewer). The Editor view is not directly part of this flow, but instead can be accessed from any of the other views. Going
-The first item in the list is “New message” button, which is a convenience shortcut to quick write a new email in the Editor view.
+back from Editor view shows the previous view of the “stack”, i.e. the view from which the user opened the Editor view.
-[[Image:H22-Modest-Accounts-view.png||frame|center|alt=Screenshot of Accounts view|Maemo 5 Accounts view]]
+==== Accounts view ====
+The design of this view is simply to list the accounts use has set up on the device. Tapping on any of the accounts opens Folders view of that account. In addition to the account name, also the time stamp of the last account refresh is shown on each list item.
+<br>
+The first item in the list is “New message” button, which is a convenience shortcut to quick write a new email in the Editor view.<br>
+[[Image:H22-Modest-Accounts-view.png|Accounts view|300px]]
+<br><br>
 ==== Folders view ====
+This view lists folders related to the selected email account. Additionally also ''Local folders'' (stored on the device), and ''Archive'' (stored on external memory card if available) are shown in the list.
-This view lists folders related to the selected email account. Additionally, ''Local folders'' (stored on the device), and ''Archive'' (stored on external memory card if available) are shown in the list.
+<br>
+The folder tree in Maemo 4 was a direct representation of the physical folder structure. In Maemo 5 the fingerable lists are flat and pannable, and expandable lists are not supported. These constraints required re-designing how subfolders are represented in the UI. A full-blown design of each-subfolder-is-a-subview was too navigation heavy approach for email application, and instead all folders and subfolders are shown in the same pannable list.
-The folder tree in Maemo 4 was a direct representation of the physical folder structure. In Maemo 5 the fingerable lists are flat and pannable, and expandable lists are not supported. These constraints required re-designing how subfolders are represented in the UI. A full-blown design of each-subfolder-is-a-subview was too navigation-heavy for an email application, and instead all folders and subfolders are shown in the same pannable list.
+<br><br>
+The depth of a folder is indicated by the amount of dots (<code>&amp;middot;</code>) placed before the name of the folder.
-The depth of a folder is indicated by the amount of dots (<code>&middot;</code>) placed before the name of the folder.
+<br><br>
 The icon in each list item represents the location of the storage (email server, local, MMC), except for the standard email folders, which have individual icons (Inbox, Drafts, Outbox, Sent).
+<br><br>
-If a folder contains new, unread messages then this status is indicated with <code>ActiveTextColor</code> on the folder name and with informative text on the right half of the list item.
+If a folder contains new, unread messages then this status is indicated with <code>ActiveTextColor</code> on the folder name and with informative text on the right half of the list item.<br>
+[[Image:H22-Modest-Folders-view.png|Folders view|300px]]
-[[Image:H22-Modest-Folders-view.png|frame|center|alt=Screenshot of folder view|Maemo 5 Folders view]]
+<br><br>
 ==== Messages view ====
+The messages view in Maemo 5 has very few changes compared to Maemo 4. The most visible changes are 1) indicating the unread status with <code>ActiveTextColor</code> and 2) the “New message” shortcut button.<br>
-The messages view in Maemo 5 has very few changes compared to Maemo 4. The most visible changes are 1) indicating the unread status with <code>ActiveTextColor</code> and 2) the “New message” shortcut button.
+[[Image:H22-Modest-Messages-view.png|Messages view|300px]]
+<br><br>
-[[Image:H22-Modest-Messages-view.png|frame|center|alt=Screenshot of Messages view|Maemo 5 Messages view]]
 ==== Viewer view ====
 The main changes in the viewer view has been to remove all less important UI elements either to view menu or to the toolbar – the subject is shown in view title, the message header only contains From, Date and Attachment fields. This design allows to maximize the screen space for the most important content (the email message itself), while giving direct access to most used actions in the toolbar.
+<table width="100%"><tr>
+<td style="vertical-align: top; width: 320px">[[Image:Diablo-Modest_viewer_view.png|Diablo Viewer view|300px]]
+</td><td style="padding-left:20px; vertical-align: top;">[[Image:H22-Modest-Viewer-view.png|Viewer view|300px]]
+</td></tr></table>
-{| class="wikitable"
+<br>
-| [[Image:Diablo-Modest_viewer_view.png|Diablo Viewer view|300px]]
-| [[Image:H22-Modest-Viewer-view.png|Viewer view|300px]]
-|}
 ==== Editor view ====
+The basic layout and logic of the Editor view remains unchanged. However, due to increasing the UI elements to finger size, following tweaks were made to this view:
-The basic layout and logic of the Editor view remains unchanged. However, due to increasing the UI elements to finger size, the following tweaks were made to this view:
 * “Send” button was moved to the right side of “from” picker button, in order to reserve the toolbar only for message formatting commands
 * Addressbook buttons were merged with the To, CC and BCC field titles to save screen space and increase usability – ''tapping directly on the content''. Also, CC and BCC fields are now hidden by default.
 * Attachment button was moved to View menu, also to save screen space.
+<table width="100%"><tr>
+<td style="vertical-align: top; width: 320px">[[Image:Diablo-Modest_editor_view.png|Diablo Editor view|300px]]
+</td><td style="padding-left:20px; vertical-align: top;">[[Image:H22-Modest-Editor-view.png|Editor view|300px]]
+</td></tr></table>
-{| class="wikitable"
+<br>
-| [[Image:Diablo-Modest_editor_view.png|Diablo Editor view|300px]]
-| [[Image:H22-Modest-Editor-view.png|Editor view|300px]]
-|}
 === Commands ===
+The following tables compare the commands in the Maemo 4 and Maemo 5 versions of the Modest email client.
-The following tables compare the commands in the Maemo 4 and Maemo 5 versions of the Modest email client.
+The Maemo 4 duplicated most of the commands between Application menu, Toolbar and Context sensitive menu.
-The Maemo 4 version duplicated most of the commands between the Application menu, Toolbar and Context sensitive menu.
+<br>
+{|border="2" cellspacing="0" cellpadding="4" width="80%"
+|bgcolor = "#D9D9D9"|'''Location'''
+|bgcolor = "#D9D9D9"|'''Menu commands in Maemo 5 Modest'''
-{| class="wikitable"
-! Location
-! Menu commands in Maemo 5 Modest
 |-
 |Accounts view menu
 |'''New account, Edit accounts, SMTP servers''', Send & receive / Stop sending, '''Settings'''
 |-
 |Folders view menu
 |'''New folder, Rename folder, Move folder, Delete folder''', Send &amp; receive/stop sending, Edit account
 |-
 |Messages view menu
 |'''New message, Move messages, Delete messages''', Folder details, Sort, Send &amp; receive/stop sending
 |-
 |Viewer view menu
 |Find in message, Move message, Forward, Mark as read, Mark as unread, Save attachments, Remove attachments, New message, Add to Contacts, Message details
 |-
 |Editor view menu
 |Check names, Undo, Show/Hide CC, Show/Hide BCC, Insert image, Add attachment, Remove attachments, Message settings, Find in message
-|}
+|}
+<br>
 Notable changes are:
 * In general, commands are specific to their view
@@ Line 148: / Line 158: @@
 * New message command only appears in Messages and Viewer view menus, as access to that command is provided by quick access button in Accounts view, Folders view (the first item in the list)
-{| class="wikitable"
-! Location
+<br>
-! Toolbar commands in Maemo 5 Modest
+{|border="2" cellspacing="0" cellpadding="4" width="80%"
+|bgcolor = "#D9D9D9"|'''Location'''
+|bgcolor = "#D9D9D9"|'''Toolbar commands in Maemo 5 Modest'''
 |-
 |Viewer view toolbar
 |Reply, Reply all, delete, load external images, previous message, next message
 |-
 |Editor view toolbar
 |Font face, Font size, Bold, Italics, Font color
-|}
+|}
+<br>
 Notable changes are:
 * The Accounts, Folders and Messages views do not have toolbar, since they contain a list without focus. This also allows maximizing the amount of rows visible.
 * The commands in toolbars are not repeated elsewhere in the UI.
-{| class="wikitable"
+<br>
-! Location
+{|border="2" cellspacing="0" cellpadding="4" width="80%"
-! context sensitive commands in Maemo 5 Modest
+|bgcolor = "#D9D9D9"|'''Location'''
+|bgcolor = "#D9D9D9"|'''context sensitive commands in Maemo 5 Modest'''
 |-
 |Messages view context sensitive menu
 |Delete, mark unread/read
-|}
+|}
+<br>
 Notable changes are:
 * Almost all the context sensitive menus were removed. Only the most important commands (targetting a single message) were included to the Messages view context sensitive menu.
 === Dialogs ===
 There are very many dialogs in the email application, mostly due to the complexity of the email handling in general. This chapter uses the Account settings dialog as the example of changes in dialogs.
@@ Line 186: / Line 203: @@
 * The account deletion is included in the Account Settings dialog directly, as the account list dialog does not have focus.
-{| class="wikitable"
+<table width="100%"><tr>
+<td style="vertical-align: top; width: 320px">[[Image:Diablo-modest-account-settings.png|Diablo account settings|300px]]
+</td><td style="padding-left:20px; vertical-align: top;">[[Image:H22-Modest-account-settings.png|Modest account settings|300px]]
+</td></tr></table>
+== Porting MaemoPad ==
+This is a practical example of porting a Diablo (Maemo 4.1) application to Fremantle (Maemo 5). The example application, MaemoPad, is a simple Notepad-like editor.
+<div align="CENTER">
+{| summary="MaemoPad"
+|+ align="BOTTOM" |'''Figure:''' MaemoPad
 |-
-| [[Image:Diablo-modest-account-settings.png|Diablo account settings|300px]]
+|
-| [[Image:H22-Modest-account-settings.png|Modest account settings|300px]]
+<div align="CENTER">[[Image:maemopad.png|Image maemopad]]</div>
 |}
-[[Category:Development]]
+</div>
-[[Category:Documentation]]
-[[Category:Fremantle]]
+Porting from Diablo to Fremantle involved mostly changes in GTK+- and Hildon-specific parts of the code, because newer versions of these libraries are now in use, and because of the new Fremantle GUI guidelines. This subsection will first explain how to install MaemoPad, and then proceeds to describing the main changes in the code. The reader is recommended to familiarize with chapters Application Development[/node7.html#chap:application_dev [[Image:crossref.png|[*]]]] and Hildon Human Interface Guidelines[/node12.html#chap:Hildon_Human_Interface_Guidelines [[Image:crossref.png|[*]]]] before this one. For reference, see GTK+ and Hildon APIs from [http://maemo.org/development/sdks/maemo_5_api_documentation/ Maemo Fremantle APIs].
+=== Installing MaemoPad ===
+MaemoPad can be installed and tested in the scratchbox environment.
+* If not already activated, activate the X86 target, go to the testing directory, and download the source package of maemopad application.
+ [sbox-FREMANTLE_ARMEL] sb-conf select FREMANTLE_X86
+ [sbox-FREMANTLE_X86 ~] mkdir maemopad
+ [sbox-FREMANTLE_X86 ~/maemopad] cd maemopad
+ [sbox-FREMANTLE_X86 ~/maemopad] apt-get source maemopad
+ ...apt output...
+* Check that you have the correct files.
+ [sbox-FREMANTLE_X86: ~/maemopad] &gt; ls -l
+ total 352
+ drwxrwxr-x  6 maemo maemo   4096 Jul 28 14:09 maemopad-2.5
+ -rw-rw-r--  1 maemo maemo    465 Jul  6 16:02 maemopad_2.5.dsc
+ -rw-rw-r--  1 maemo maemo 346129 Jul  6 16:02 maemopad_2.5.tar.gz
+* Go to the <code>maemopad-2.5</code> source directory, and build the maemopad package with <code>dpkg-buildpackage</code> command as shown here:
+ [sbox-FREMANTLE_X86: ~/maemopad] &gt; cd maemopad-2.5
+ [sbox-FREMANTLE_X86: ~/maemopad/maemopad-2.5] &gt; dpkg-buildpackage -rfakeroot
+ dpkg-buildpackage: source package is maemopad
+ dpkg-buildpackage: source version is 2.5
+ dpkg-buildpackage: source changed by Soumya Bijjal &lt;soumya.3.bijjal@nokia.com&gt;
+ dpkg-buildpackage: host architecture i386
+ dpkg-buildpackage: source version without epoch 2.3
+ .... etc ....
+* Install the newly compiled <code>maemopad_2.5_i386.deb</code> file inside the Scratchbox environment:
+ [sbox-FREMANTLE_X86: ~/maemopad] &gt; dpkg -i maemopad_2.5_i386.deb
+ ... output from dpkg ...
+* Make sure you have the SDK UI running in Xephyr.
+* You can now run MaemoPad by selecting it from the menu.
+The MaemoPad source code resides in folder <code>maemopad-2.5/src:</code>
+ [sbox-FREMANTLE_X86: ~/maemopad] ls maemopad-2.5/src
+ total 280
+ -rw-rw-r--  1 maemo maemo 25491 Jul 28 15:45 Makefile
+ -rw-rw-r--  1 maemo maemo   491 Jul 28 14:09 Makefile.am
+ -rw-rw-r--  1 maemo maemo 23238 Jul 28 14:09 Makefile.in
+ -rwxrwxr-x  1 maemo maemo 83433 Jul 28 15:45 maemopad
+ -rw-rw-r--  1 maemo maemo 82928 Jul 28 15:45 maemopad-maemopad-window.o
+ -rw-rw-r--  1 maemo maemo 18564 Jul 28 15:45 maemopad-main.o
+ -rw-rw-r--  1 maemo maemo 20400 Jul 28 14:09 maemopad-window.c
+ -rw-rw-r--  1 maemo maemo  2391 Jul 28 14:09 maemopad-window.h
+ -rw-rw-r--  1 maemo maemo  2193 Jul 28 14:09 main.c
+For comparison, the Diablo version of MaemoPad can also be examined:
+ [sbox-FREMANTLE_X86: ~/maemopad] &gt; svn export https://garage.maemo.org/svn/\
+ maemoexamples/tags/maemo_4.1/maemopad diablo_maemopad
+ [sbox-FREMANTLE_X86: ~/src] ls -lR diablo_maemopad/src
+ diablo_maemopad/src/:
+ total 16
+ -rw-rw-r--  1 maemo maemo  537 May 15  2008 Makefile.am
+ -rw-rw-r--  1 maemo maemo  557 May 15  2008 appdata.h
+ -rw-rw-r--  1 maemo maemo 2789 Dec  3  2008 main.c
+ drwxrwxr-x  2 maemo maemo 4096 Aug 20 11:53 ui
+ diablo_maemopad/src/ui:
+ total 36
+ -rw-rw-r--  1 maemo maemo 12163 Dec  3  2008 callbacks.c
+ -rw-rw-r--  1 maemo maemo  1682 Oct 29  2008 callbacks.h
+ -rw-rw-r--  1 maemo maemo 14982 Dec  3  2008 interface.c
+ -rw-rw-r--  1 maemo maemo  2695 Dec  3  2008 interface.h
+=== Code reorganization ===
+If one takes a look at MaemoPad source code for Diablo and Fremantle, there are many bug fixes, and there have been major refractorizations. These are, however, not necessary for porting and are not discussed here in detail. The main change is reorganizing the files, which is already apparent from the <code>ls</code> lists above:
+* <code>src/ui</code> subfolder has been dropped
+* <code>src/ui/callbacks.c</code> and <code>src/ui/interface</code> have been combined into <code>src/maemopad-window.c</code>, similarly for header files
+* <code>appdata.h</code> is included in <code>main.c</code>
+* In <code>src/Makefile.am</code>, <code>maemopad_SOURCES = &lt;list of source files&gt;</code> has been updated correspondingly.
+=== Device-specific changes ===
+The previous device, N810, had a separate full-screen and ESC keys that were dropped from the new device. In MaemoPad, pressing the full-screen key was replaced by Ctrl-F. This required the following addition
+* maemopad-window.c
+ #include <gdk/gdkkeysyms.h>
+to include GDK definition for key "f", <code>GDK_f</code> to replace the earlier <code>HILDON_HARDKEY_FULLSCREEN</code>. Callback for Esc was completely removed. The full-screen action itself was principally unchanged. The key event function was modified correspondingly:
+* Diablo callbacks.c
+ gboolean key_press(GtkWidget * widget, GdkEventKey * event,
+                      gpointer data)
+ {
+     ...
+     if (event->keyval == HILDON_HARDKEY_FULLSCREEN && !keypressed){
+         keypressed = TRUE;
+     ...
+     if (event->keyval == HILDON_HARDKEY_ESC && !keypressed){
+         keypressed = TRUE;
+     ...
+* Fremantle maemopad-window.c
+ static gboolean maemopad_window_on_key_press(GtkWidget *widget, GdkEventKey *event,
+                      gpointer data)
+ {
+     ...
+     if (event->keyval == GDK_f && (event->state & GDK_CONTROL_MASK) && !self- >key_pressed) {
+         self->key_pressed = TRUE;
+     ...
+=== Dropped libraries ===
+Hildon help library, libhildonhelp, was dropped from Fremantle so all dependencies to it had to be removed.
+libhildonhelp-dev needs to removed from build depencies:
+Diablo: debian/control:
+ Build-Depends: debhelper (&gt;= 4.0.0), intltool,
+  libhildon1-dev, libgtk2.0-dev, libosso-gnomevfs2-dev,
+  libglib2.0-dev, libdbus-glib-1-dev, libosso-dev, libmodest-dbus-client-dev,
+  conbtdialogs-dev,libhildonhelp-dev, libhildonfm2-dev, osso-af-settings
+Fremantle: debian/control:
+ Build-Depends: debhelper (&gt;= 4.0.0), intltool,
+  libhildon1-dev, libgtk2.0-dev, libosso-gnomevfs2-dev,
+  libglib2.0-dev, libdbus-glib-1-dev, libosso-dev, libmodest-dbus-client-dev,
+  conbtdialogs-dev,  libhildonfm2-dev, osso-af-settings
+Callback and all other help stuff removed:
+* Diablo callbacks.c
+ /* help */
+ void callback_help( GtkAction * action, gpointer data )
+ {
+     osso_return_t retval;
+     /* connect pointer to our AppUIData struct */
+     AppUIData *mainview = NULL;
+     mainview = ( AppUIData * ) data;
+     g_assert(mainview != NULL && mainview->data != NULL );
+     retval = hildon_help_show(
+       mainview->data->osso, /* osso_context */
+       HELP_TOPIC_ID,        /* topic id */
+       HILDON_HELP_SHOW_DIALOG);
+ }
+* Diablo interface.c
+ GtkWidget *help = NULL;
+ help = gtk_menu_item_new_with_label( _("Help") );
+ gtk_menu_append( main_menu, help );
+ g_signal_connect( G_OBJECT( help ), "activate",
+ G_CALLBACK ( callback_help ), main );
+* Diablo callbacks.c
+ #include <hildon/hildon-help.h>
+ #define HELP_TOPIC_ID "Example_MaemoPad_Content"
+* Diablo configure.ac:
+ PKG_CHECK_MODULES(HILDON, hildon-1 hildon-fm-2 hildon-help conbtdialogs)
+* Fremantle configure.ac:
+ PKG_CHECK_MODULES(HILDON, hildon-1 hildon-fm-2 conbtdialogs)
+Removed data/help directory which contained an example help file.
+Some files contained items related to it and they were also removed:
+* Diablo data/Makefile.am:
+ helpfile_engb_DATA = help/en_GB/MaemoPad.xml
+ -EXTRA_DIST = $(serviceentry_DATA) $(desktopentry_DATA) $(icon_26x26_DATA) $(icon_40x40_DATA)
+ $(icon_scalable_DATA) *$(helpfile_engb_DATA)*
+Diablo data/Makefile.am:
+ <nowiki>
+ # Help file install directory
+ helpfile_engbdir=$datadir/hildon-help/en_GB
+ AC_SUBST(helpfile_engbdir) NOT YET
+ </nowiki>
+=== GUI design changes ===
+Because of new UI guidelines, a toolbar that was at the bottom of the MaemoPadwindow in Diablo was dropped. This meant removing the function <code>create_toolbar</code> from <code>interface.c</code>, line 282 and its declaration on line 47 of the same file. Also the call for the function was dropped from the same file. Likewise, related declarations were dropped:
+* interface.h
+ /* Toolbar */
+ GtkWidget* toolbar;
+ GtkWidget* iconw;
+ GtkToolItem* new_tb;
+ GtkToolItem* open_tb;
+ ...
+ GtkToolItem* fullscreen_tb;
+Also the menu system was changed. In Diablo, a GtkMenu was used, but it was replaced with a HildonAppMenu in Fremantle, shown in Figure [localhost#fig:maemopad_menu [[Image:crossref.png|[*]]]].
+<div align="CENTER">
+{| summary="MaemoPad Menu"
+|+ align="BOTTOM" |'''Figure:''' MaemoPad Menu
+|-
+|
+<div align="CENTER">[[Image:maemopad_menu.png|Image maemopad_menu]]</div>
+|}
+</div>
+Function <code>create_menu()</code> is responsible for creating the menus in both versions:
+* Diablo interface.c
+ static void create_menu( AppUIData *main )
+ {
+     /* Create needed handles */
+     GtkMenu *main_menu;
+     GtkWidget *file_menu, *edit_menu, *sendvia_menu;
+     GtkWidget *separator = NULL;
+     GtkWidget *close = NULL;
+     /* Create main menu and new menus for submenus in our drop down menu */
+     main_menu = GTK_MENU( gtk_menu_new () );
+     file_menu = gtk_menu_new ();
+     edit_menu = gtk_menu_new ();
+     sendvia_menu = gtk_menu_new ();
+     /* Create the menu items */
+     main->file_item = gtk_menu_item_new_with_label ( _("File") );
+     main->new_item = gtk_menu_item_new_with_label ( _("New") );
+     main->open_item = gtk_menu_item_new_with_label ( _("Open") );
+     ...
+     /* Add menu items to right menus */
+     gtk_menu_append( main_menu, main->file_item );
+     gtk_menu_append( file_menu, main->new_item );
+     gtk_menu_append( file_menu, main->open_item );
+     ...
+     gtk_menu_append( main_menu, close );
+     /* Add submenus to the right items */
+     gtk_menu_item_set_submenu( GTK_MENU_ITEM (main->file_item), file_menu );
+     gtk_menu_item_set_submenu( GTK_MENU_ITEM (main->edit_item), edit_menu );
+     gtk_menu_item_set_submenu( GTK_MENU_ITEM (main->sendvia_item),   sendvia_menu );
+     /* Attach the callback functions to the activate signal */
+     g_signal_connect( G_OBJECT( main->new_item ), "activate",
+ 		      G_CALLBACK ( callback_file_new), main );
+     g_signal_connect( G_OBJECT( main->open_item ), "activate",
+ 		      G_CALLBACK ( callback_file_open), main );
+     ...
+     g_signal_connect( G_OBJECT( close ), "activate", gtk_main_quit, NULL );
+     /* Add menu to HildonWindow */
+     hildon_window_set_menu(main->data->window, main_menu);
+     /* We need to show menu items */
+     gtk_widget_show_all( GTK_WIDGET( main_menu ) );
+ }
+* Fremantle maemopad-window.c
+  static GtkWidget* add_menu_item (GtkWidget *main_menu, const gchar* title,
+     GCallback clicked_callback, gpointer user_data)
+ {
+   HildonAppMenu *app_menu = HILDON_APP_MENU (main_menu);
+   /* Create a button, add it, and return it: */
+   GtkWidget *button = hildon_button_new_with_text (HILDON_SIZE_AUTO,
+         HILDON_BUTTON_ARRANGEMENT_VERTICAL, title, NULL);
+   gtk_widget_show (button);
+   g_signal_connect_after (button, "clicked",
+   	G_CALLBACK (clicked_callback), user_data);
+   hildon_app_menu_append (app_menu, GTK_BUTTON (button));
+   return button;
+ }
+ /* Create the menu items needed: */
+ static void create_menu (MaemopadWindow *self)
+ {
+   /* Create needed handles */
+   GtkWidget *main_menu = hildon_app_menu_new ();
+   /* Create the menu items */
+   self->new_item = add_menu_item (main_menu, _("New"),
+     G_CALLBACK (&maemopad_window_on_menu_file_new), self);
+   self->open_item = add_menu_item (main_menu, _("Open"),
+     G_CALLBACK (&maemopad_window_on_menu_file_open), self);
+   ...
+    self->close_item = add_menu_item (main_menu, _("Close"),
+     G_CALLBACK (&maemopad_window_on_menu_close), self);
+   /* Add menu to HildonWindow */
+   hildon_window_set_app_menu (
+     HILDON_WINDOW (self),
+     HILDON_APP_MENU (main_menu));
+   /* We need to show menu items */
+   gtk_widget_show_all (GTK_WIDGET (main_menu));
+ }
+As a result to changes in the .c file, the following menu widget declarations used in Diablo became unnecessary:
+* interface.h
+ GtkWidget *file_item;
+ GtkWidget *edit_item;
+ GtkWidget *sendvia_item;
+Menu callbacks were also changed. There were some changes in the callbacks themselves as a result of code reorganizations, but the main change from the menu viewpoint was that the 1st arguments of the callbacks were changed from GtkAction to GtkButton, like in the following example.
+* Diablo callbacks.c
+ void callback_file_new(GtkAction * action, gpointer data)
+* Fremantle maemopad-window.c
+ static void maemopad_window_on_menu_file_new (GtkButton *button, gpointer data)
+=== Other updates in GTK+ and Hildon ===
+* Rich text support was changed with the new GTK+, as described in [http://live.gnome.org/Maemo/Gtk210Migration Maemo-GTK+ 2.6 to 2.10 Migration].This required editing two lines: <br />Part of function create_textarea() in Diablo interface.c
+ /* Enable Rich Text Support */
+ gtk_text_buffer_set_can_paste_rich_text ( main->buffer, TRUE );
+ gtk_text_buffer_set_rich_text_format ( main->buffer, "RTF" );
+Part of function create_textarea() in Fremantle maemopad-window.c
+ /* Enable Rich Text Support */
+ gtk_text_buffer_register_serialize_tagset (self->buffer, "RTF");
+ gtk_text_buffer_register_deserialize_tagset (self->buffer, "RTF");
+* HildonFontSelectionDialog was deprecated and replaced with a GtkFontButton.
+In Diablo, the font callback was a callback to a regular GtkAction:
+callback.c
+ void callback_font( GtkAction * action, gpointer data )
+ {
+     ...
+     new_font = interface_font_chooser( mainview );
+     /* if we got a new font from chooser -> change font */
+     if( new_font != NULL ) {
+         mainview->font_desc = new_font;
+         gtk_widget_modify_font ( mainview->textview, mainview->font_desc );
+     }
+ }
+Function <code>callback_font</code> got the font from an auxiliary function <code>interface_font_chooser()</code> and then modified the font in the text view. The auxiliary function <code>interface_font_chooser()</code> in turn opened a HildonFontSelectionDialog that returned the font parameters:
+callback.c
+ /* Font chooser */
+ PangoFontDescription* interface_font_chooser( AppUIData * main )
+ {
+     ...
+     font = pango_font_description_new();
+     /* create dialog */
+     dialog = HILDON_FONT_SELECTION_DIALOG ( hildon_font_selection_dialog_new( NULL, NULL ) );
+     gtk_widget_show_all (GTK_WIDGET(dialog));
+     if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_OK)
+     {
+         g_object_get(G_OBJECT(dialog),
+                     "family", &family,
+                     "size", &size,
+                     "bold", &bold,
+                     "italic", &italic,
+                     NULL);
+         pango_font_description_set_family(font, family);
+         pango_font_description_set_size(font, size * PANGO_SCALE);
+         if (bold) {
+             pango_font_description_set_weight(font, PANGO_WEIGHT_BOLD);
+         } else {
+             pango_font_description_set_weight(font, PANGO_WEIGHT_NORMAL);
+         }
+         if (italic) {
+             pango_font_description_set_style(font, PANGO_STYLE_ITALIC);
+         } else {
+             pango_font_description_set_style(font, PANGO_STYLE_NORMAL);
+         }
+     }
+     gtk_widget_destroy(GTK_WIDGET(dialog));
+     return font;
+ }
+Instead of the deprecated HildonFontSelectionDialog, Fremantle uses a GtkFontButton directly in the font button callback:
+* maemopad-window.c
+ /* font */
+ static void maemopad_window_on_font_set (GtkFontButton *button, gpointer data)
+ {
+   ...
+   font_name = gtk_font_button_get_font_name (button);
+   if (!font_name)
+     return;
+   new_font = pango_font_description_from_string (font_name);
+   /* Change the font used in the GtkTextView */
+   if (new_font) {
+     if (self->font_desc)
+       pango_font_description_free (self->font_desc);
+      self->font_desc = new_font;
+      gtk_widget_modify_font (self->textview, self->font_desc);
+   }
+ }
+This GtkFontButton was initialized in function <code>create_menu()</code> (see above) in maemopad-window.c so that it would respond to the <code>"font-set"</code> signal and call the callback above:
+  self->font_item = gtk_font_button_new ();
+  gtk_widget_show (self->font_item);
+  g_signal_connect_after (self->font_item, "font-set",
+    G_CALLBACK (maemopad_window_on_font_set), self);
+  hildon_app_menu_append (HILDON_APP_MENU (main_menu), GTK_BUTTON (self->font_item));
+* Instead of GtkTextView, a [http://maemo.org/api_refs/5.0/beta/hildon/HildonTextView.html HildonTextView] is now used.
+* Diablo callback.c
+ /* Create the text area */
+ void create_textarea( AppUIData *main )
+ {
+     /* Text view */
+     main->textview = gtk_text_view_new ();
+     ...
+     /* Get handle */
+     main->buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (main->textview));
+     ...
+ }
+* Fremantle maemopad-window.c
+ static void create_textarea (MaemopadWindow *self)
+ {
+     /* Text view */
+     self->textview = hildon_text_view_new ();
+     ....
+     /* Get handle */
+     self->buffer = hildon_text_view_get_buffer (GTK_TEXT_VIEW (self->textview));
+ }
+* All Hildon applications should now initialize hildon before using it. In maemopad this is done by calling <code>hildon_gtk_init()</code> which also calls <code>gtk_init()</code> so the original call can be removed:
+Diablo main.c
+ /* Init the gtk - must be called before any hildon stuff */
+ gtk_init( &argc, &argv );
+Fremantle main.c
+ /* Inititialize GTK+ and hildon: */
+ hildon_gtk_init( &argc, &argv );