[Xfce4-commits] <libxfce4ui:nick/docs> Add xfce_dialog_show_help function.

Nick Schermer noreply at xfce.org
Sat Dec 31 14:38:02 CET 2011


Updating branch refs/heads/nick/docs
         to dd4edcc01b443e566150cfae860a22eb2699a0da (commit)
       from 4a14ef81cdc6f3e45b63eb42ca41c6af50c9c0c4 (commit)

commit dd4edcc01b443e566150cfae860a22eb2699a0da
Author: Nick Schermer <nick at xfce.org>
Date:   Sat Dec 31 14:34:34 2011 +0100

    Add xfce_dialog_show_help function.
    
    Function that can be used to redirect to the docs.xfce.org
    (or other location, see --with-manual-website).

 configure.ac.in               |   12 +++
 docs/libxfce4ui-sections.txt  |    1 +
 libxfce4ui/libxfce4ui.symbols |    1 +
 libxfce4ui/xfce-dialogs.c     |  199 ++++++++++++++++++++++++++++++++++++++++-
 libxfce4ui/xfce-dialogs.h     |    5 +
 5 files changed, 217 insertions(+), 1 deletions(-)

diff --git a/configure.ac.in b/configure.ac.in
index eb658a8..272e046 100644
--- a/configure.ac.in
+++ b/configure.ac.in
@@ -163,6 +163,17 @@ else
     AC_MSG_RESULT([not set])
 fi
 
+dnl *********************************************
+dnl *** Check for vendor specific information ***
+dnl *********************************************
+AC_MSG_CHECKING([for a custom manual website location])
+AC_ARG_WITH([manual-website],
+AC_HELP_STRING([--with-manual-website=URI], [Specify an optional manual website, defaults to http://docs.xfce.org.]),
+    [with_manual_website="$withval"],
+    [with_manual_website="http://docs.xfce.org/redirect.php"])
+AC_DEFINE_UNQUOTED([MANUAL_WEBSITE], ["$with_manual_website"], [Documentation website])
+AC_MSG_RESULT([$with_manual_website])
+
 dnl *********************************************************
 dnl *** Optional support for the Glade Interface Designer ***
 dnl *********************************************************
@@ -335,4 +346,5 @@ echo "in this text file: \"${datarootdir}/xfce4/vendorinfo\""
 else
 echo "* Vendor:                    none"
 fi
+echo "* Manual website:            $with_manual_website"
 echo
diff --git a/docs/libxfce4ui-sections.txt b/docs/libxfce4ui-sections.txt
index cd74590..12fc10c 100644
--- a/docs/libxfce4ui-sections.txt
+++ b/docs/libxfce4ui-sections.txt
@@ -38,6 +38,7 @@ xfce_gtk_window_center_on_active_screen
 xfce_message_dialog_new
 xfce_message_dialog_new_valist
 xfce_message_dialog
+xfce_dialog_show_help
 xfce_dialog_show_info
 xfce_dialog_show_warning
 xfce_dialog_show_error
diff --git a/libxfce4ui/libxfce4ui.symbols b/libxfce4ui/libxfce4ui.symbols
index 80a2290..d88ce12 100644
--- a/libxfce4ui/libxfce4ui.symbols
+++ b/libxfce4ui/libxfce4ui.symbols
@@ -56,6 +56,7 @@ xfce_sm_client_shutdown_hint_get_type
 /* xfce-dialogs functions */
 #if IN_HEADER(__XFCE_DIALOGS_H__)
 #if IN_SOURCE(__XFCE_DIALOGS_C__)
+xfce_dialog_show_help
 xfce_dialog_show_info G_GNUC_PRINTF (3, 4)
 xfce_dialog_show_warning G_GNUC_PRINTF (3, 4)
 xfce_dialog_show_error G_GNUC_PRINTF (3, 4)
diff --git a/libxfce4ui/xfce-dialogs.c b/libxfce4ui/xfce-dialogs.c
index 5bf4e71..aef83d8 100644
--- a/libxfce4ui/xfce-dialogs.c
+++ b/libxfce4ui/xfce-dialogs.c
@@ -25,10 +25,12 @@
 #ifdef HAVE_STRING_H
 #include <string.h>
 #endif
-
 #ifdef HAVE_STDARG_H
 #include <stdarg.h>
 #endif
+#ifdef HAVE_LOCALE_H
+#include <locale.h>
+#endif
 
 #include <gtk/gtk.h>
 #include <libxfce4util/libxfce4util.h>
@@ -39,6 +41,199 @@
 #include <libxfce4ui/libxfce4ui-private.h>
 #include <libxfce4ui/libxfce4ui-alias.h>
 
+#define NOTNULL(str) ((str) != NULL ? (str) : "")
+
+
+
+static void
+xfce_dialog_show_help_auto_toggled (GtkWidget *button)
+{
+  XfceRc   *rc;
+  gboolean  active = FALSE;
+
+  if (button != NULL)
+    active = gtk_toggle_button_get_active (GTK_TOGGLE_BUTTON (button));
+
+  rc = xfce_rc_config_open (XFCE_RESOURCE_CONFIG, "xfce4/help.rc", FALSE);
+  if (rc != NULL)
+    {
+      xfce_rc_write_bool_entry (rc, "auto-online", active);
+      xfce_rc_close (rc);
+    }
+}
+
+
+
+static void
+xfce_dialog_show_help_uri (GdkScreen *screen,
+                           GtkWindow *parent,
+                           GString   *uri)
+{
+  GError *error = NULL;
+
+  g_return_if_fail (GDK_IS_SCREEN (screen));
+  g_return_if_fail (parent == NULL || GTK_IS_WINDOW (parent));
+
+  if (!gtk_show_uri (screen, uri->str, gtk_get_current_event_time (), &error))
+    {
+      xfce_dialog_show_error (parent, error,
+          _("Failed to open web browser for online documentation"));
+      g_error_free (error);
+    }
+}
+
+
+
+static void
+xfce_dialog_show_help_response (GtkWidget *dialog,
+                                gint       response_id,
+                                GString   *uri)
+{
+  gtk_widget_hide (dialog);
+
+  if (response_id == GTK_RESPONSE_YES)
+    {
+      xfce_dialog_show_help_uri (gtk_widget_get_screen (dialog),
+                                 gtk_window_get_transient_for (GTK_WINDOW (dialog)),
+                                 uri);
+    }
+  else
+    {
+      /* unset auto */
+      xfce_dialog_show_help_auto_toggled (NULL);
+    }
+
+  g_string_free (uri, TRUE);
+  gtk_widget_destroy (dialog);
+}
+
+
+
+/**
+ * xfce_dialog_show_help:
+ * @parent      : transient parent of the dialog, or %NULL.
+ * @application : name of the component opening the help page or %NULL. If the
+ *                value is %NULL the target will be the main page of the
+ *                documentation website.
+ * @page        : subpage of the application on the website or %NULL.
+ * @offset      : anchor offset in @page or %NULL.
+ *
+ * Asks the user to visit the online documentation. If confirmed, it will open
+ * the webbrowser and redirect the user to the correct location.
+ *
+ * Appart from the @application, @page and @offset the following information
+ * is also send to the server: user language and the xfce_version_string().
+ *
+ * Since 4.10
+ */
+void
+xfce_dialog_show_help (GtkWindow   *parent,
+                       const gchar *application,
+                       const gchar *page,
+                       const gchar *offset)
+{
+  GtkWidget   *dialog;
+  const gchar *name;
+  gchar       *primary;
+  GString     *uri;
+  gchar       *locale;
+  GtkWidget   *message_box;
+  GtkWidget   *button;
+  XfceRc      *rc;
+  gboolean     auto_online;
+  GdkScreen   *screen;
+
+  g_return_if_fail (parent == NULL || GTK_IS_WINDOW (parent));
+
+  /* get the user's locale without encoding */
+  locale = g_strdup (setlocale (LC_MESSAGES, NULL));
+  if (G_LIKELY (locale != NULL))
+    locale = g_strdelimit (locale, ".", '\0');
+  else
+    locale = g_strdup ("C");
+
+  /* build the redirect uri */
+  uri = g_string_new (MANUAL_WEBSITE);
+  g_string_append_printf (uri, "?v=%s&l=%s", xfce_version_string (), locale);
+  g_free (locale);
+
+  if (application != NULL)
+    g_string_append_printf (uri, "&a=%s", application);
+  if (page != NULL)
+    g_string_append_printf (uri, "&p=%s", page);
+  if (offset != NULL)
+    g_string_append_printf (uri, "&o=%s", offset);
+
+  /* check if we should automatically go online */
+  rc = xfce_rc_config_open (XFCE_RESOURCE_CONFIG, "xfce4/help.rc", TRUE);
+  if (rc != NULL)
+    {
+      auto_online = xfce_rc_read_bool_entry (rc, "auto-online", FALSE);
+      xfce_rc_close (rc);
+
+      if (auto_online)
+        {
+          if (parent != NULL)
+            screen = gtk_window_get_screen (GTK_WINDOW (parent));
+          else
+            screen = xfce_gdk_screen_get_active (NULL);
+
+          xfce_dialog_show_help_uri (screen, parent, uri);
+          g_string_free (uri, TRUE);
+
+          return;
+        }
+    }
+
+  /* try to get a translated name of the application */
+  name = g_get_application_name ();
+  if (g_strcmp0 (name, g_get_prgname ()) == 0)
+    name = NULL;
+
+  /* try to get a decent primary text */
+  if (name != NULL)
+    primary = g_strdup_printf (_("Do you want to read the %s manual online?"), name);
+  else
+    primary = g_strdup (_("Do you want to read the manual online?"));
+
+  dialog = xfce_message_dialog_new (parent,
+                                    _("Online Documentation"),
+                                    GTK_STOCK_DIALOG_QUESTION,
+                                    primary,
+                                    _("You will be redirected to the documentation website "
+                                      "where the help pages are maintained and translated."),
+                                    GTK_STOCK_CANCEL, GTK_RESPONSE_NO,
+                                    XFCE_BUTTON_TYPE_MIXED,
+                                        GTK_STOCK_HELP, _("_Read Online"),
+                                        GTK_RESPONSE_YES,
+                                    NULL);
+  g_free (primary);
+
+#if GTK_CHECK_VERSION (2, 22, 0)
+  message_box = gtk_message_dialog_get_message_area (GTK_MESSAGE_DIALOG (dialog));
+#else
+  message_box = gtk_widget_get_parent (GTK_MESSAGE_DIALOG (dialog)->label);
+  g_return_if_fail (GTK_IS_VBOX (message_box));
+#endif
+
+  button = gtk_check_button_new_with_mnemonic (_("_Always go directly to the online documentation"));
+  gtk_box_pack_end (GTK_BOX (message_box), button, FALSE, TRUE, 0);
+  g_signal_connect (G_OBJECT (button), "toggled",
+      G_CALLBACK (xfce_dialog_show_help_auto_toggled), NULL);
+  gtk_widget_show (button);
+
+  /* don't focus the checkbutton */
+  gtk_dialog_set_default_response (GTK_DIALOG (dialog), GTK_RESPONSE_YES);
+  button = gtk_dialog_get_widget_for_response (GTK_DIALOG (dialog), GTK_RESPONSE_YES);
+  gtk_widget_grab_focus (button);
+
+  /* show the dialog without locking the mainloop */
+  gtk_window_set_modal (GTK_WINDOW (dialog), parent != NULL);
+  g_signal_connect (G_OBJECT (dialog), "response",
+      G_CALLBACK (xfce_dialog_show_help_response), uri);
+  gtk_window_present (GTK_WINDOW (dialog));
+}
+
 
 
 /**
@@ -283,6 +478,7 @@ xfce_message_dialog_new_valist (GtkWindow   *parent,
 
           /* add a mixed button to the dialog */
           button = xfce_gtk_button_new_mixed (stock_id, label);
+          gtk_widget_set_can_default (button, TRUE);
           gtk_dialog_add_action_widget (GTK_DIALOG (dialog), button, response);
           gtk_widget_show (button);
         }
@@ -311,6 +507,7 @@ xfce_message_dialog_new_valist (GtkWindow   *parent,
           /* create button and add it to the dialog */
           button = gtk_button_new_with_label (label);
           gtk_button_set_image (GTK_BUTTON (button), image);
+          gtk_widget_set_can_default (button, TRUE);
           gtk_dialog_add_action_widget (GTK_DIALOG (dialog), button, response);
           gtk_widget_show (button);
         }
diff --git a/libxfce4ui/xfce-dialogs.h b/libxfce4ui/xfce-dialogs.h
index 1c2f390..f004c3f 100644
--- a/libxfce4ui/xfce-dialogs.h
+++ b/libxfce4ui/xfce-dialogs.h
@@ -31,6 +31,11 @@ G_BEGIN_DECLS
 #define XFCE_BUTTON_TYPE_MIXED  "button-mixed"
 #define XFCE_BUTTON_TYPE_PIXBUF "button-pixbuf"
 
+void       xfce_dialog_show_help          (GtkWindow    *parent,
+                                           const gchar  *application,
+                                           const gchar  *page,
+                                           const gchar  *offset);
+
 void       xfce_dialog_show_info          (GtkWindow    *parent,
                                            const gchar  *secondary_text,
                                            const gchar  *primary_format,


More information about the Xfce4-commits mailing list