[tepl] AmtkFactory: add functions to create GtkMenuItem's

[Sébastien Wilmet <swilmet src gnome org>]

commit 18baca38c5a5c30d7ff1fa8c7543256203b2c72c
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Mon Aug 7 20:28:49 2017 +0200

    AmtkFactory: add functions to create GtkMenuItem's

 amtk/amtk-factory.c                  |  207 +++++++++++++++++++++++++++++++++-
 amtk/amtk-factory.h                  |    7 +
 docs/reference/tepl-3.0-sections.txt |    2 +
 3 files changed, 213 insertions(+), 3 deletions(-)
---
diff --git a/amtk/amtk-factory.c b/amtk/amtk-factory.c
index 90576d3..a770a27 100644
--- a/amtk/amtk-factory.c
+++ b/amtk/amtk-factory.c
@@ -20,6 +20,7 @@
 #include "amtk-factory.h"
 #include "amtk-action-info.h"
 #include "amtk-action-info-central-store.h"
+#include "amtk-menu-item.h"
 #include "amtk-enum-types.h"
 
 /**
@@ -44,9 +45,8 @@
  * variants: a simple form which takes the value of the
  * #AmtkFactory:default-flags property, and the same function with the `_full`
  * suffix which takes an #AmtkFactoryFlags argument and ignores the
- * #AmtkFactory:default-flags. See for example
- * amtk_factory_menu_create_menu_item() and
- * amtk_factory_menu_create_menu_item_full().
+ * #AmtkFactory:default-flags. See for example amtk_factory_create_menu_item()
+ * and amtk_factory_create_menu_item_full().
  *
  * # Static objects # {#amtk-factory-static-objects}
  *
@@ -58,6 +58,81 @@
  * static, created on application startup. Updating automatically menu and
  * toolbar items is out of scope for the Amtk library. If for example action
  * accelerators can be modified at run-time, the menu needs to be re-generated.
+ *
+ * # Menus
+ *
+ * Some notes about the functions that create #GtkMenuItem's:
+ * - If not ignored by an #AmtkFactoryFlags, the first accelerator returned by
+ *   amtk_action_info_get_accels() is set to the #GtkAccelLabel of the
+ *   #GtkMenuItem.
+ * - If not ignored by an #AmtkFactoryFlags, the tooltip is set with
+ *   amtk_menu_item_set_long_description(), which permits to display it in a
+ *   #GtkStatusbar with amtk_application_window_connect_menu_to_statusbar().
+ *
+ * ## Code example to create a menu
+ *
+ * How to create a #GtkMenuBar with #AmtkFactory. Each submenu is created by a
+ * separate function, to make the code clearer.
+ *
+ * |[
+ * static GtkWidget *
+ * create_file_submenu (void)
+ * {
+ *   GtkMenuShell *file_submenu;
+ *   AmtkFactory *factory;
+ *
+ *   file_submenu = GTK_MENU_SHELL (gtk_menu_new ());
+ *
+ *   factory = amtk_factory_new_with_default_application ();
+ *   gtk_menu_shell_append (file_submenu, amtk_factory_create_menu_item (factory, "win.open"));
+ *   gtk_menu_shell_append (file_submenu, amtk_factory_create_menu_item (factory, "win.save"));
+ *   gtk_menu_shell_append (file_submenu, gtk_separator_menu_item_new ());
+ *   gtk_menu_shell_append (file_submenu, amtk_factory_create_menu_item (factory, "app.quit"));
+ *   g_object_unref (factory);
+ *
+ *   return GTK_WIDGET (file_submenu);
+ * }
+ *
+ * static GtkWidget *
+ * create_help_submenu (void)
+ * {
+ *   GtkMenuShell *help_submenu;
+ *   AmtkFactory *factory;
+ *
+ *   help_submenu = GTK_MENU_SHELL (gtk_menu_new ());
+ *
+ *   factory = amtk_factory_new_with_default_application ();
+ *   gtk_menu_shell_append (help_submenu, amtk_factory_create_menu_item (factory, "app.about"));
+ *   g_object_unref (factory);
+ *
+ *   return GTK_WIDGET (help_submenu);
+ * }
+ *
+ * static GtkWidget *
+ * create_menu_bar (void)
+ * {
+ *   GtkWidget *file_menu_item;
+ *   GtkWidget *help_menu_item;
+ *   GtkWidget *menu_bar;
+ *
+ *   file_menu_item = gtk_menu_item_new_with_mnemonic ("_File");
+ *   gtk_menu_item_set_submenu (GTK_MENU_ITEM (file_menu_item),
+ *                              create_file_submenu ());
+ *
+ *   help_menu_item = gtk_menu_item_new_with_mnemonic ("_Help");
+ *   gtk_menu_item_set_submenu (GTK_MENU_ITEM (help_menu_item),
+ *                              create_help_submenu ());
+ *
+ *   menu_bar = gtk_menu_bar_new ();
+ *   gtk_menu_shell_append (GTK_MENU_SHELL (menu_bar), file_menu_item);
+ *   gtk_menu_shell_append (GTK_MENU_SHELL (menu_bar), help_menu_item);
+ *
+ *   // Additionally, it is a good place to call
+ *   // amtk_action_info_store_check_all_used() here.
+ *
+ *   return menu_bar;
+ * }
+ * ]|
  */
 
 struct _AmtkFactoryPrivate
@@ -287,6 +362,132 @@ amtk_factory_set_default_flags (AmtkFactory      *factory,
 }
 
 /**
+ * amtk_factory_create_menu_item:
+ * @factory: an #AmtkFactory.
+ * @action_name: an action name.
+ *
+ * Creates a new #GtkMenuItem for @action_name with the
+ * #AmtkFactory:default-flags.
+ *
+ * Returns: (transfer floating): a new #GtkMenuItem for @action_name.
+ * Since: 3.0
+ */
+GtkWidget *
+amtk_factory_create_menu_item (AmtkFactory *factory,
+                              const gchar *action_name)
+{
+       g_return_val_if_fail (AMTK_IS_FACTORY (factory), NULL);
+       g_return_val_if_fail (action_name != NULL, NULL);
+
+       return amtk_factory_create_menu_item_full (factory,
+                                                  action_name,
+                                                  factory->priv->default_flags);
+}
+
+/**
+ * amtk_factory_create_menu_item_full:
+ * @factory: an #AmtkFactory.
+ * @action_name: an action name.
+ * @flags: #AmtkFactoryFlags.
+ *
+ * This function ignores the #AmtkFactory:default-flags property and takes the
+ * @flags argument instead.
+ *
+ * Returns: (transfer floating): a new #GtkMenuItem for @action_name.
+ * Since: 3.0
+ */
+GtkWidget *
+amtk_factory_create_menu_item_full (AmtkFactory      *factory,
+                                   const gchar      *action_name,
+                                   AmtkFactoryFlags  flags)
+{
+       AmtkActionInfoCentralStore *central_store;
+       AmtkActionInfo *action_info;
+       GtkMenuItem *menu_item;
+       const gchar * const *accels;
+       const gchar *icon_name;
+       const gchar *tooltip;
+
+       g_return_val_if_fail (AMTK_IS_FACTORY (factory), NULL);
+       g_return_val_if_fail (action_name != NULL, NULL);
+
+       central_store = amtk_action_info_central_store_get_singleton ();
+       action_info = amtk_action_info_central_store_lookup (central_store, action_name);
+
+       if (action_info == NULL)
+       {
+               g_warning ("%s(): action name '%s' not found.",
+                          G_STRFUNC,
+                          action_name);
+
+               return NULL;
+       }
+
+       menu_item = GTK_MENU_ITEM (gtk_menu_item_new ());
+
+       if ((flags & AMTK_FACTORY_IGNORE_GACTION) == 0)
+       {
+               gtk_actionable_set_action_name (GTK_ACTIONABLE (menu_item), action_name);
+       }
+
+       if ((flags & AMTK_FACTORY_IGNORE_LABEL) == 0)
+       {
+               gtk_menu_item_set_use_underline (menu_item, TRUE);
+               gtk_menu_item_set_label (menu_item, amtk_action_info_get_label (action_info));
+       }
+
+       /* Set accel before setting icon, because
+        * amtk_menu_item_set_icon_name() adds a GtkBox.
+        */
+       accels = amtk_action_info_get_accels (action_info);
+       if ((flags & AMTK_FACTORY_IGNORE_ACCELS) == 0 &&
+           (flags & AMTK_FACTORY_IGNORE_ACCELS_FOR_DOC) == 0 &&
+           accels != NULL && accels[0] != NULL)
+       {
+               guint accel_key;
+               GdkModifierType accel_mods;
+
+               gtk_accelerator_parse (accels[0], &accel_key, &accel_mods);
+
+               if (accel_key != 0 || accel_mods != 0)
+               {
+                       GtkWidget *child;
+
+                       child = gtk_bin_get_child (GTK_BIN (menu_item));
+
+                       gtk_accel_label_set_accel (GTK_ACCEL_LABEL (child),
+                                                  accel_key,
+                                                  accel_mods);
+               }
+       }
+
+       icon_name = amtk_action_info_get_icon_name (action_info);
+       if ((flags & AMTK_FACTORY_IGNORE_ICON) == 0 &&
+           icon_name != NULL)
+       {
+               amtk_menu_item_set_icon_name (menu_item, icon_name);
+       }
+
+       tooltip = amtk_action_info_get_tooltip (action_info);
+       if ((flags & AMTK_FACTORY_IGNORE_TOOLTIP) == 0 &&
+           tooltip != NULL)
+       {
+               amtk_menu_item_set_long_description (menu_item, tooltip);
+       }
+
+       if ((flags & AMTK_FACTORY_IGNORE_ACCELS) == 0 &&
+           (flags & AMTK_FACTORY_IGNORE_ACCELS_FOR_APP) == 0 &&
+           factory->priv->app != NULL)
+       {
+               gtk_application_set_accels_for_action (factory->priv->app, action_name, accels);
+       }
+
+       amtk_action_info_mark_as_used (action_info);
+
+       return GTK_WIDGET (menu_item);
+}
+
+/**
  * amtk_factory_create_tool_button:
  * @factory: an #AmtkFactory.
  * @action_name: an action name.
diff --git a/amtk/amtk-factory.h b/amtk/amtk-factory.h
index eb45b6d..4a6483d 100644
--- a/amtk/amtk-factory.h
+++ b/amtk/amtk-factory.h
@@ -97,6 +97,13 @@ AmtkFactoryFlags     amtk_factory_get_default_flags                  (AmtkFactory 
*factory);
 void                   amtk_factory_set_default_flags                  (AmtkFactory      *factory,
                                                                         AmtkFactoryFlags  default_flags);
 
+GtkWidget *            amtk_factory_create_menu_item                   (AmtkFactory *factory,
+                                                                        const gchar *action_name);
+
+GtkWidget *            amtk_factory_create_menu_item_full              (AmtkFactory      *factory,
+                                                                        const gchar      *action_name,
+                                                                        AmtkFactoryFlags  flags);
+
 GtkToolItem *          amtk_factory_create_tool_button                 (AmtkFactory *factory,
                                                                         const gchar *action_name);
 
diff --git a/docs/reference/tepl-3.0-sections.txt b/docs/reference/tepl-3.0-sections.txt
index 2059383..399b132 100644
--- a/docs/reference/tepl-3.0-sections.txt
+++ b/docs/reference/tepl-3.0-sections.txt
@@ -106,6 +106,8 @@ amtk_factory_new_with_default_application
 amtk_factory_get_application
 amtk_factory_get_default_flags
 amtk_factory_set_default_flags
+amtk_factory_create_menu_item
+amtk_factory_create_menu_item_full
 amtk_factory_create_tool_button
 amtk_factory_create_tool_button_full
 <SUBSECTION Standard>