HildonApp/HildonAppView to HildonProgram/HildonWindow migration guide

Introduction

During the migration to the IT-2006 edition (before the hildon consolidation project) of the Internet Tablet software, a new API to handle applications and top-level windows in the Hildon framework is introduced. This API is intended to replace the current HildonApp/HildonAppView API.

This document intends to explain the changes required to port applications from the old API (HildonApp/HildonAppView) to the new one (HildonProgram/HildonWindow). It also details the new functionalities introduced with the API change.

Migration

Windows replace views

The former API had introduced the concept of Application Views. One application was limited to have only one top-level window (HildonApp). Several HildonAppView could be interchanged as content of this top-level window, to give the user the illusion of several windows.

The technical difficulties in managing several windows per application have been overcome. Thus the new API removes these limitations and allows the applications to have several top-level windows (HildonWindow).

A HildonProgram is a GObject representing the whole application. In this sense it replaces the former HildonApp. However, the HildonApp was also a representation of the only top-level window that the application had. This is no longer the case, a HildonProgram is not a GtkWidget.

Only one HildonProgram can be created per process. It is accessed with hildon program get instance.

HildonWindows shall be registered to the HildonProgram in a similar way as HildonAppViews were registered to the HildonApp. hildon program add window is used for that purpose. As the method name suggests, several HildonWindows are likely to be registered to a HildonProgram.

  /* Create needed variables */
  HildonApp *app;
  HildonAppView *appview;
  
  /* Initialize GTK. */
  gtk_init (&argc, &argv);
  
  /* Create the hildon application and setup the title */
  app = HILDON_APP (hildon_app_new ());
  hildon_app_set_title (app, "Menu Example");
  
  /* Create HildonAppView and set it to HildonApp */
  appview = HILDON_APPVIEW (hildon_appview_new(NULL));
  hildon_app_set_appview (app, appview);
  
  /* Add example label to appview */
  gtk_container_add (GTK_CONTAINER (appview),
  gtk_label_new ("Menu Example"));
  
  /* Begin the main application */
  gtk_widget_show_all (GTK_WIDGET (app));
  gtk_main();
  
   /* Exit */
  return 0;

is replaced in the new API with:

  /* Create needed variables */
  HildonProgram *program;
  HildonWindow *window;

  /* Initialize GTK. */
  gtk_init (&argc, &argv);

  /* Create the hildon program and setup the title */
  program = HILDON_PROGRAM (hildon_program_get_instance());
  g_set_application_name ("Menu Example");

  /* Create HildonWindow and set it to HildonProgram */
  window = HILDON_WINDOW (hildon_window_new());
  hildon_program_add_window (program, window);

  /* Add example label to window */
  gtk_container_add (GTK_CONTAINER(window),
  gtk_label_new ("Menu Example"));
  
  /* Begin the main application */
  gtk_widget_show_all (GTK_WIDGET(window));

  gtk_main();
  /* Exit */
  return 0;

Menus

In the previous API, the HildonAppView would create its menu implicitely on the first call to hildon appview get menu(). This was confusing and not co- herent with usual GTK+ APIs.

The new API requires the programmer to create his GtkMenu externally, then add it to the HildonWindow with hildon window set menu().

  GtkMenu *menu;
  menu = hildon_appview_get_menu (appview);
  fill_in_menu (menu);

is replaced with

  GtkMenu *menu;
  menu = gtk_menu_new ();
  fill_in_menu (menu);
  hildon_window_set_menu (menu);

Toolbars

In the previous API, the programmer had to access an internal GtkVBox inside the HildonAppView to add toolbars. This is no longer the case, hildon window add toolbar shall be used for this purpose.

  GtkToolbar *toolbar;
  toolbar = create_toolbar (); 
  
  /* Add toolbar to ’vbox’ of HildonAppView */
  gtk_box_pack_end (GTK_BOX (appview->vbox), main_toolbar, TRUE, TRUE, 0);

is replaced with

  GtkToolbar *toolbar;
  toolbar = create_toolbar ();
  
  /* Add toolbar to the HildonWindow */
  hildon_window_add_toolbar (window, toolbar);

The find toolbar is handled in a similar way. It shall be added to the HildonWindow with hildon window add toolbar. It will always be displayed on top.

Hibernation capability

In the former API the programmer could tell the Hildon Task Navigator whether or not her application is ready to be set to hibernation (background-killed) by using hildon app set killable.

A similar functionality is present in the new API, through hildon program set can hibernate().

Top-most status

In the former API, the top-most status of the HildonApp could be tracked with the topmost-status-acquire and topmost-status-lose signals.

These signals are replaced by a single property, is-topmost, whose changes can be tracked, like any other properties, with the notify::is-topmost signal.

Both the HildonProgram and the HildonWindows have this property. The HildonWindow’s property tells whether or not this specific top-level window is currently activated by the window manager. The HildonProgram’s one tells whether one of the process’ window (HildonWindow or other top-level window such as GtkDialog) is currently activated by the window manager.

void topmost_status_acquire (HildonApp *app, gpointer data)
{
     hildon_app_set_killable (app, FALSE);
}

void topmost_status_lose (HildonApp *app, gpointer data)
{
     save_state();
     hildon_app_set_killable (app, TRUE);
}

g_signal_connect (G_OBJECT (app), "topmost-status-acquire",
                  G_CALLBACK (topmost_status_acquire), NULL);

g_signal_connect (G_OBJECT (app), "topmost-status-lose",
                  G_CALLBACK (topmost_status_lose), NULL);

is replaced with

static void program_is_topmost_notify (GObject *self,
                                       GParamSpec *property_param,
                                       gpointer null)
{
     HildonProgram *program = HILDON_PROGRAM (self);
     if (hildon_program_get_is_topmost (program))
     {
          hildon_program_set_can_hibernate (program, FALSE);
     }
     else
     {
         save_state();
         hildon_program_set_can_hibernate (program, TRUE);
     }
}

g_signal_connect (G_OBJECT (program), "notify::is-topmost",
                  G_CALLBACK (topmost-status-notify), NULL);

New functionalities

Window-specific setting

Having real top-level windows allow to send window-specific commands to the window manager and task navigator.

Applications are now able to tell the task navigator that some window requires the user’s attention. This will trigger the blinking of the window’s icon in the task navigator.

gtk_window_set_urgency_hint (GTK_WINDOW (window), TRUE);

Similarly applications are now able to change the icon representing each of their HildonWindow in the task navigator by using the gtk window set icon set of functions.

GdkPixbuf *icon = create_icon();
gtk_window_set_icon (GTK_WINDOW (window), icon);

The title can be set per window with:

gtk_window_set_title (GTK_WINDOW (window), "Window Title");

If the application name was set with g set application name(), it will precede the window title in the title bar.

Program-wide settings

The HildonProgram object provides the programmer with commodities to set program-wide settings to all the registered HildonWindow.

The programmer can create a common menu which will be shared (memory-wise and functionally) by all the windows. A window can override this common menu by having its own menu.

GtkMenu *common_menu = create_common_menu ();
GtkMenu *window_specific_menu = create_window_specific_menu ();

hildon_program_set_common_menu (program, common_menu);
hildon_window_set_menu (second_window, window_specific_menu);

Similarly, a common toolbar can be shared among all HildonWindow. Widows can add window specific toolbars. The common toolbar will be displayed on the bottom of the stack of toolbars.

GtkToolbar *common_toolbar = create_common_toolbar ();
GtkToolbar *window_specific_toolbar = create_window_specific_toolbar ();
hildon_program_set_common_toolbar (program, common_toolbar);
hildon_window_add_toolbar (second_window, window_specific_toolbar);