GApplication: make distinction about menus

Rename g_application_set_menu to g_application_set_app_menu and make a
couple of fixups.  Clarify the documentation about exactly what this
menu is meant to be.

Add g_application_set_menubar and document that as well.

docs/reference/gio/gio-sections.txt

@@ -2815,8 +2815,10 @@ g_application_get_flags
 g_application_set_flags
 <SUBSECTION>
 g_application_set_action_group
-g_application_set_menu
+g_application_set_app_menu
-g_application_get_menu
+g_application_get_app_menu
+g_application_set_menubar
+g_application_get_menubar
 <SUBSECTION>
 g_application_get_is_registered
 g_application_get_is_remote

gio/gapplication.c

@@ -162,7 +162,8 @@ struct _GApplicationPrivate
   gchar             *id;
 
   GActionGroup      *actions;
-  GMenuModel        *menu;
+  GMenuModel        *app_menu;
+  GMenuModel        *menubar;
 
   guint              inactivity_timeout_id;
   guint              inactivity_timeout;
@@ -186,7 +187,8 @@ enum
   PROP_IS_REMOTE,
   PROP_INACTIVITY_TIMEOUT,
   PROP_ACTION_GROUP,
-  PROP_MENU
+  PROP_APP_MENU,
+  PROP_MENUBAR
 };
 
 enum
@@ -408,9 +410,12 @@ g_application_set_property (GObject      *object,
                                       g_value_get_object (value));
       break;
 
-    case PROP_MENU:
+    case PROP_APP_MENU:
-      g_application_set_menu (application,
+      g_application_set_app_menu (application, g_value_get_object (value));
-                              g_value_get_object (value));
+      break;
+
+    case PROP_MENUBAR:
+      g_application_set_menubar (application, g_value_get_object (value));
       break;
 
     default:
@@ -449,12 +454,20 @@ g_application_set_action_group (GApplication *application,
 }
 
 /**
- * g_application_set_menu:
+ * g_application_set_app_menu:
  * @application: a #GApplication
- * @menu: (allow-none): a #GMenuModel, or %NULL
+ * @app_menu: (allow-none): a #GMenuModel, or %NULL
  *
- * Sets or unsets the menu associated with the application. The menu
+ * Sets or unsets the application menu for @application.
- * provides representation data for the exported actions of @application.
+ *
+ * The application menu is a single menu containing items that typically
+ * impact the application as a whole, rather than acting on a specific
+ * window or document.  For example, you would expect to see
+ * "Preferences" or "Quit" in an application menu, but not "Save" or
+ * "Print".
+ *
+ * If supported, the application menu will be rendered by the desktop
+ * environment.
  *
  * It is an error to call this function after the application has been
  * registered.
@@ -462,38 +475,105 @@ g_application_set_action_group (GApplication *application,
  * Since: 2.32
  */
 void
-g_application_set_menu (GApplication *application,
+g_application_set_app_menu (GApplication *application,
-                        GMenuModel   *menu)
+                            GMenuModel   *app_menu)
 {
   g_return_if_fail (G_IS_APPLICATION (application));
   g_return_if_fail (!application->priv->is_registered);
 
-  if (application->priv->menu != NULL)
+  if (app_menu != application->priv->app_menu)
-    g_object_unref (application->priv->menu);
+    {
+      if (application->priv->app_menu != NULL)
+        g_object_unref (application->priv->app_menu);
 
-  application->priv->menu = menu;
+      application->priv->app_menu = app_menu;
 
-  if (application->priv->menu != NULL)
+      if (application->priv->app_menu != NULL)
-    g_object_ref (application->priv->menu);
+        g_object_ref (application->priv->app_menu);
+
+      g_object_notify (G_OBJECT (application), "app-menu");
+    }
 }
 
 /**
- * g_application_get_menu:
+ * g_application_get_app_menu:
  * @application: a #GApplication
  *
- * Returns the menu model that has been set
+ * Returns the menu model that has been set with
- * with g_application_set_menu().
+ * g_application_set_app_menu().
  *
- * Returns: the #GMenuModel associated with @application
+ * Returns: the application menu of @application
  *
  * Since: 2.32
  */
 GMenuModel *
-g_application_get_menu (GApplication *application)
+g_application_get_app_menu (GApplication *application)
 {
   g_return_val_if_fail (G_IS_APPLICATION (application), NULL);
 
-  return application->priv->menu;
+  return application->priv->app_menu;
+}
+
+/**
+ * g_application_set_menubar:
+ * @application: a #GApplication
+ * @menubar: (allow-none): a #GMenuModel, or %NULL
+ *
+ * Sets or unsets the menubar for windows of @application.
+ *
+ * This is a menubar in the traditional sense.
+ *
+ * Depending on the desktop environment, this may appear at the top of
+ * each window, or at the top of the screen.  In some environments, if
+ * both the application menu and the menubar are set, the application
+ * menu will be presented as if it were the first item of the menubar.
+ * Other environments treat the two as completely separate -- for
+ * example, the application menu may be rendered by the desktop shell
+ * while the menubar (if set) remains in each individual window.
+ *
+ * It is an error to call this function after the application has been
+ * registered.
+ *
+ * Since: 2.32
+ */
+void
+g_application_set_menubar (GApplication *application,
+                            GMenuModel   *menubar)
+{
+  g_return_if_fail (G_IS_APPLICATION (application));
+  g_return_if_fail (!application->priv->is_registered);
+
+  if (menubar != application->priv->menubar)
+    {
+      if (application->priv->menubar != NULL)
+        g_object_unref (application->priv->menubar);
+
+      application->priv->menubar = menubar;
+
+      if (application->priv->menubar != NULL)
+        g_object_ref (application->priv->menubar);
+
+      g_object_notify (G_OBJECT (application), "menubar");
+    }
+}
+
+/**
+ * g_application_get_menubar:
+ * @application: a #GApplication
+ *
+ * Returns the menu model that has been set with
+ * g_application_set_menubar().
+ *
+ * Returns: the menubar for windows of @application
+ *
+ * Since: 2.32
+ */
+GMenuModel *
+g_application_get_menubar (GApplication *application)
+{
+  g_return_val_if_fail (G_IS_APPLICATION (application), NULL);
+
+  return application->priv->menubar;
 }
 
 static void
@@ -631,10 +711,17 @@ g_application_class_init (GApplicationClass *class)
                          G_TYPE_ACTION_GROUP,
                          G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS));
 
-  g_object_class_install_property (object_class, PROP_MENU,
+  g_object_class_install_property (object_class, PROP_APP_MENU,
-    g_param_spec_object ("menu",
+    g_param_spec_object ("app-menu",
-                         P_("Menu model"),
+                         P_("Application menu"),
-                         P_("The menu that the application exports"),
+                         P_("The GMenuModel for the application menu"),
+                         G_TYPE_MENU_MODEL,
+                         G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS));
+
+  g_object_class_install_property (object_class, PROP_MENUBAR,
+    g_param_spec_object ("menubar",
+                         P_("Menubar"),
+                         P_("The GMenuModel for the menubar"),
                          G_TYPE_MENU_MODEL,
                          G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS));
 

gio/gapplication.h

@@ -151,9 +151,13 @@ void                    g_application_set_flags                         (GApplic
 void                    g_application_set_action_group                  (GApplication             *application,
                                                                          GActionGroup             *action_group);
 
-void                    g_application_set_menu                          (GApplication             *application,
+void                    g_application_set_app_menu                      (GApplication             *application,
-                                                                         GMenuModel                *menu);
+                                                                         GMenuModel               *app_menu);
-GMenuModel             *g_application_get_menu                          (GApplication             *application);
+GMenuModel             *g_application_get_app_menu                      (GApplication             *application);
+
+void                    g_application_set_menubar                       (GApplication             *application,
+                                                                         GMenuModel               *menubar);
+GMenuModel *            g_application_get_menubar                       (GApplication             *application);
 
 gboolean                g_application_get_is_registered                 (GApplication             *application);
 gboolean                g_application_get_is_remote                     (GApplication             *application);

gio/gapplicationimpl-dbus.c

@@ -241,7 +241,7 @@ g_application_impl_destroy (GApplicationImpl *impl)
       if (impl->actions_exported)
         g_action_group_dbus_export_stop (impl->app);
       if (impl->menu_exported)
-        g_menu_model_dbus_export_stop (g_application_get_menu (impl->app));
+        g_menu_model_dbus_export_stop (g_application_get_app_menu (impl->app));
 
       g_dbus_connection_call (impl->session_bus,
                               "org.freedesktop.DBus",
@@ -341,11 +341,11 @@ g_application_impl_register (GApplication       *application,
         }
       impl->actions_exported = TRUE;
 
-      if (g_application_get_menu (impl->app))
+      if (g_application_get_app_menu (impl->app))
         {
           if (!g_menu_model_dbus_export_start (impl->session_bus,
                                                impl->object_path,
-                                               g_application_get_menu (impl->app),
+                                               g_application_get_app_menu (impl->app),
                                                error))
             {
               g_action_group_dbus_export_stop (impl->app);
@@ -388,7 +388,7 @@ g_application_impl_register (GApplication       *application,
 
           if (impl->menu_exported)
             {
-              g_menu_model_dbus_export_stop (g_application_get_menu (impl->app));
+              g_menu_model_dbus_export_stop (g_application_get_app_menu (impl->app));
               impl->menu_exported = FALSE;
             }
 
@@ -428,7 +428,7 @@ g_application_impl_register (GApplication       *application,
       impl->actions_exported = FALSE;
       if (impl->menu_exported)
         {
-          g_menu_model_dbus_export_stop (g_application_get_menu (impl->app));
+          g_menu_model_dbus_export_stop (g_application_get_app_menu (impl->app));
           impl->menu_exported = FALSE;
         }
 

gio/tests/gapplication-example-menu.c

@@ -68,7 +68,7 @@ add_menu (GApplication *app)
   g_menu_append (menu, "About Example", "about");
   g_menu_append (menu, "Quit", "quit");
 
-  g_application_set_menu (app, G_MENU_MODEL (menu));
+  g_application_set_app_menu (app, G_MENU_MODEL (menu));
 
   g_object_unref (menu);
 }