GNOME Goal: Replace gnome_help and gnome-open calls with gtk_show_uri

Currently many GNOME apps still use gnome_help calls and code that uses launching of gnome-open to open files. The gnome_help API and the gnome-open are part of the libgnome library which is deprecated.

GTK+ 2.13.1 contains a new API call gtk_show_uri to replace gnome_help and gnome-open. Programs that don't depend on libgnome usually spawn xdg-open. Replacing that with gtk_show_uri is a cleaner solution.

/**
 * gtk_show_uri:
 * @screen: screen to show the uri on or %NULL for the default screen
 * @uri: the uri to show
 * @timestamp: a timestamp to prevent focus stealing. 
 * @error: a #GError that is returned in case of errors
 *
 * This is a convenience function for launching the default application 
 * to show the uri. The uri must be of a form understood by GIO. Typical
 * examples are 
 * <simplelist>
 *   <member><filename>file:///home/gnome/pict.jpg</filename></member>
 *   <member><filename>http://www.gnome.org</filename></member>
 *   <member><filename>mailto:me&commat;gnome.org</filename></member>
 * </simplelist>
 * Ideally the timestamp is taken from the event triggering 
 * the gtk_show_uri() call. If timestamp is not known you can take 
 * %GDK_CURRENT_TIME.
 *
 * This function can be used as a replacement for gnome_vfs_url_show() 
 * and gnome_url_show().
 *
 * Returns: %TRUE on success, %FALSE on error.
 *
 * Since: 2.14
 */

Opening help file with gtk_show_uri

E.g opening the help for cheese can be done like this

screen = gtk_widget_get_screen (cheese_window->window);
gtk_show_uri (screen, "ghelp:cheese",  gtk_get_current_event_time (), &error);

if (error != NULL)
{
  GtkWidget *d;
  d = gtk_message_dialog_new (GTK_WINDOW (cheese_window->window), 
                              GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT,
                              GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, 
                              "%s", _("Unable to open help file"));
  gtk_message_dialog_format_secondary_text (GTK_MESSAGE_DIALOG (d),
                                                                  "%s", error->message);
  g_signal_connect (d, "response", G_CALLBACK (gtk_widget_destroy), NULL);
  gtk_window_present (GTK_WINDOW (d));

  g_error_free (error);
}

Opening a specific section like the intro for cheese can be done like this

screen = gtk_widget_get_screen (cheese_window->window);

gtk_show_uri (screen, "ghelp:cheese?intro",  gtk_get_current_event_time (), &error);

if (error != NULL)
{
  GtkWidget *d;
  d = gtk_message_dialog_new (GTK_WINDOW (cheese_window->window), 
                              GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT,
                              GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, 
                              "%s", _("Unable to open help file"));
  gtk_message_dialog_format_secondary_text (GTK_MESSAGE_DIALOG (d),
                                                                  "%s", error->message);
  g_signal_connect (d, "response", G_CALLBACK (gtk_widget_destroy), NULL);
  gtk_window_present (GTK_WINDOW (d));

  g_error_free (error);
}

Note that for the timestamp to pass to gtk_show_uri, you should take the event time as taken from the GdkEventKey, GdkEventButton etc event that triggers the action, or use gtk_get_current_event_time(). Only as a last resort should GDK_CURRENT_TIME be used.

Comments

Status of this goal

Note: Updated automatical stats can be found at http://www.gnome.org/~fpeters/reports/gnome_help.html

Above are the states and corresponding markup to update the modules state table below.