Pileus Git - ~andy/gtk/blob - gtk/gtkapplication.c

   1 /*
   2  * Copyright © 2010 Codethink Limited
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the licence, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  *
  19  * Author: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 #include "config.h"
  23
  24 #include <stdlib.h>
  25 #ifdef HAVE_UNISTD_H
  26 #include <unistd.h>
  27 #endif
  28 #include <string.h>
  29
  30 #include "gtkapplication.h"
  31 #include "gtkmarshalers.h"
  32 #include "gtkmain.h"
  33 #include "gtkapplicationwindow.h"
  34 #include "gtkaccelmapprivate.h"
  35 #include "gactionmuxer.h"
  36
  37 #ifdef GDK_WINDOWING_QUARTZ
  38 #include "gtkquartz-menu.h"
  39 #import <Cocoa/Cocoa.h>
  40 #endif
  41
  42 #include <gdk/gdk.h>
  43 #ifdef GDK_WINDOWING_X11
  44 #include <gdk/x11/gdkx.h>
  45 #endif
  46
  47 /**
  48  * SECTION:gtkapplication
  49  * @title: GtkApplication
  50  * @short_description: Application class
  51  *
  52  * #GtkApplication is a class that handles many important aspects
  53  * of a GTK+ application in a convenient fashion, without enforcing
  54  * a one-size-fits-all application model.
  55  *
  56  * Currently, GtkApplication handles GTK+ initialization, application
  57  * uniqueness, provides some basic scriptability and desktop shell integration
  58  * by exporting actions and menus and manages a list of toplevel windows whose
  59  * life-cycle is automatically tied to the life-cycle of your application.
  60  *
  61  * While GtkApplication works fine with plain #GtkWindows, it is recommended
  62  * to use it together with #GtkApplicationWindow.
  63  *
  64  * To set an application menu on a GtkApplication, use
  65  * g_application_set_app_menu(). The #GMenuModel that this function
  66  * expects is usually constructed using #GtkBuilder, as seen in the
  67  * following example. To set a menubar that will be automatically picked
  68  * up by #GApplicationWindows, use g_application_set_menubar(). GTK+
  69  * makes these menus appear as expected, depending on the platform
  70  * the application is running on.
  71  *
  72  * <figure label="Menu integration in OS X">
  73  * <graphic fileref="bloatpad-osx.png" format="PNG"/>
  74  * </figure>
  75  *
  76  * <figure label="Menu integration in GNOME">
  77  * <graphic fileref="bloatpad-gnome.png" format="PNG"/>
  78  * </figure>
  79  *
  80  * <example id="gtkapplication"><title>A simple application</title>
  81  * <programlisting>
  82  * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/bloatpad.c">
  83  *  <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  84  * </xi:include>
  85  * </programlisting>
  86  * </example>
  87  */
  88
  89 enum {
  90   WINDOW_ADDED,
  91   WINDOW_REMOVED,
  92   LAST_SIGNAL
  93 };
  94
  95 static guint gtk_application_signals[LAST_SIGNAL];
  96
  97 G_DEFINE_TYPE (GtkApplication, gtk_application, G_TYPE_APPLICATION)
  98
  99 struct _GtkApplicationPrivate
 100 {
 101   GList *windows;
 102
 103 #ifdef GDK_WINDOWING_X11
 104   GDBusConnection *session;
 105   gchar *window_prefix;
 106   guint next_id;
 107 #endif
 108
 109 #ifdef GDK_WINDOWING_QUARTZ
 110   GActionMuxer *muxer;
 111   GMenu *combined;
 112 #endif
 113 };
 114
 115 #ifdef GDK_WINDOWING_X11
 116 typedef struct
 117 {
 118   guint action_export_id;
 119   guint window_id;
 120 } GtkApplicationWindowInfo;
 121
 122 static void
 123 gtk_application_window_realized_x11 (GtkWindow *window,
 124                                      gpointer   user_data)
 125 {
 126   GtkApplication *application = user_data;
 127   GtkApplicationWindowInfo *info;
 128   GdkWindow *gdkwindow;
 129   gchar *window_path;
 130   const gchar *unique_id;
 131   const gchar *app_id;
 132
 133   gdkwindow = gtk_widget_get_window (GTK_WIDGET (window));
 134
 135   if (!GDK_IS_X11_WINDOW (gdkwindow))
 136     return;
 137
 138   info = g_object_get_data (G_OBJECT (window), "GtkApplication::window-info");
 139
 140   window_path = g_strdup_printf ("%s%d", application->priv->window_prefix, info->window_id);
 141   gdk_x11_window_set_utf8_property (gdkwindow, "_DBUS_OBJECT_PATH", window_path);
 142   g_free (window_path);
 143
 144   unique_id = g_dbus_connection_get_unique_name (application->priv->session);
 145   gdk_x11_window_set_utf8_property (gdkwindow, "_DBUS_UNIQUE_NAME", unique_id);
 146
 147   app_id = g_application_get_application_id (G_APPLICATION (application));
 148   gdk_x11_window_set_utf8_property (gdkwindow, "_DBUS_APPLICATION_ID", app_id);
 149 }
 150
 151 static void
 152 gtk_application_window_added_x11 (GtkApplication *application,
 153                                   GtkWindow      *window)
 154 {
 155   GtkApplicationWindowInfo *info;
 156
 157   if (application->priv->session == NULL)
 158     return;
 159
 160   if (!GTK_IS_APPLICATION_WINDOW (window))
 161     return;
 162
 163   /* GtkApplicationWindow associates with us when it is first created,
 164    * so surely it's not realized yet...
 165    */
 166   g_assert (!gtk_widget_get_realized (GTK_WIDGET (window)));
 167
 168   /* ...but we want to know when it is. */
 169   g_signal_connect (window, "realize", G_CALLBACK (gtk_application_window_realized_x11), application);
 170
 171   info = g_slice_new (GtkApplicationWindowInfo);
 172   do
 173     {
 174       gchar *window_path;
 175
 176       info->window_id = application->priv->next_id++;
 177       window_path = g_strdup_printf ("%s%d", application->priv->window_prefix, info->window_id);
 178       info->action_export_id = g_dbus_connection_export_action_group (application->priv->session, window_path,
 179                                                                       G_ACTION_GROUP (window), NULL);
 180       g_free (window_path);
 181     }
 182   while (!info->action_export_id);
 183
 184   g_object_set_data (G_OBJECT (window), "GtkApplication::window-info", info);
 185 }
 186
 187 static void
 188 gtk_application_window_removed_x11 (GtkApplication *application,
 189                                     GtkWindow      *window)
 190 {
 191   GtkApplicationWindowInfo *info;
 192
 193   if (application->priv->session == NULL)
 194     return;
 195
 196   if (!GTK_IS_APPLICATION_WINDOW (window))
 197     return;
 198
 199   info = g_object_steal_data (G_OBJECT (window), "GtkApplication::window-info");
 200
 201   g_dbus_connection_unexport_action_group (application->priv->session, info->action_export_id);
 202
 203   g_slice_free (GtkApplicationWindowInfo, info);
 204 }
 205
 206 static gchar *
 207 window_prefix_from_appid (const gchar *appid)
 208 {
 209   gchar *appid_path, *iter;
 210
 211   appid_path = g_strconcat ("/", appid, "/windows/", NULL);
 212   for (iter = appid_path; *iter; iter++)
 213     {
 214       if (*iter == '.')
 215         *iter = '/';
 216
 217       if (*iter == '-')
 218         *iter = '_';
 219     }
 220
 221   return appid_path;
 222 }
 223
 224 static void
 225 gtk_application_startup_x11 (GtkApplication *application)
 226 {
 227   const gchar *application_id;
 228
 229   application_id = g_application_get_application_id (G_APPLICATION (application));
 230   application->priv->session = g_bus_get_sync (G_BUS_TYPE_SESSION, NULL, NULL);
 231   application->priv->window_prefix = window_prefix_from_appid (application_id);
 232 }
 233
 234 static void
 235 gtk_application_shutdown_x11 (GtkApplication *application)
 236 {
 237   g_free (application->priv->window_prefix);
 238   application->priv->window_prefix = NULL;
 239   if (application->priv->session)
 240     {
 241       g_object_unref (application->priv->session);
 242       application->priv->session = NULL;
 243     }
 244 }
 245 #endif
 246
 247 #ifdef GDK_WINDOWING_QUARTZ
 248 static void
 249 gtk_application_menu_changed_quartz (GObject    *object,
 250                                      GParamSpec *pspec,
 251                                      gpointer    user_data)
 252 {
 253   GtkApplication *application = GTK_APPLICATION (object);
 254   GMenu *combined;
 255
 256   combined = g_menu_new ();
 257   g_menu_append_submenu (combined, "Application", g_application_get_app_menu (G_APPLICATION (object)));
 258   g_menu_append_section (combined, NULL, g_application_get_menubar (G_APPLICATION (object)));
 259
 260   gtk_quartz_set_main_menu (G_MENU_MODEL (combined), G_ACTION_OBSERVABLE (application->priv->muxer));
 261 }
 262
 263 static void
 264 gtk_application_startup_quartz (GtkApplication *application)
 265 {
 266   [NSApp finishLaunching];
 267
 268   application->priv->muxer = g_action_muxer_new ();
 269   g_action_muxer_insert (application->priv->muxer, "app", G_ACTION_GROUP (application));
 270
 271   g_signal_connect (application, "notify::app-menu", G_CALLBACK (gtk_application_menu_changed_quartz), NULL);
 272   g_signal_connect (application, "notify::menubar", G_CALLBACK (gtk_application_menu_changed_quartz), NULL);
 273   gtk_application_menu_changed_quartz (G_OBJECT (application), NULL, NULL);
 274 }
 275
 276 static void
 277 gtk_application_shutdown_quartz (GtkApplication *application)
 278 {
 279   g_signal_handlers_disconnect_by_func (application, gtk_application_menu_changed_quartz, NULL);
 280
 281   g_object_unref (application->priv->muxer);
 282   application->priv->muxer = NULL;
 283 }
 284
 285 static void
 286 gtk_application_focus_changed (GtkApplication *application,
 287                                GtkWindow      *window)
 288 {
 289   if (G_IS_ACTION_GROUP (window))
 290     g_action_muxer_insert (application->priv->muxer, "win", G_ACTION_GROUP (window));
 291   else
 292     g_action_muxer_remove (application->priv->muxer, "win");
 293 }
 294 #endif
 295
 296 static gboolean
 297 gtk_application_focus_in_event_cb (GtkWindow      *window,
 298                                    GdkEventFocus  *event,
 299                                    GtkApplication *application)
 300 {
 301   GtkApplicationPrivate *priv = application->priv;
 302   GList *link;
 303
 304   /* Keep the window list sorted by most-recently-focused. */
 305   link = g_list_find (priv->windows, window);
 306   if (link != NULL && link != priv->windows)
 307     {
 308       priv->windows = g_list_remove_link (priv->windows, link);
 309       priv->windows = g_list_concat (link, priv->windows);
 310     }
 311
 312 #ifdef GDK_WINDOWING_QUARTZ
 313   gtk_application_focus_changed (application, window);
 314 #endif
 315
 316   return FALSE;
 317 }
 318
 319 static void
 320 gtk_application_startup (GApplication *application)
 321 {
 322   G_APPLICATION_CLASS (gtk_application_parent_class)
 323     ->startup (application);
 324
 325   gtk_init (0, 0);
 326
 327 #ifdef GDK_WINDOWING_X11
 328   gtk_application_startup_x11 (GTK_APPLICATION (application));
 329 #endif
 330
 331 #ifdef GDK_WINDOWING_QUARTZ
 332   gtk_application_startup_quartz (GTK_APPLICATION (application));
 333 #endif
 334 }
 335
 336 static void
 337 gtk_application_shutdown (GApplication *application)
 338 {
 339 #ifdef GDK_WINDOWING_X11
 340   gtk_application_shutdown_x11 (GTK_APPLICATION (application));
 341 #endif
 342
 343 #ifdef GDK_WINDOWING_QUARTZ
 344   gtk_application_shutdown_quartz (GTK_APPLICATION (application));
 345 #endif
 346
 347   G_APPLICATION_CLASS (gtk_application_parent_class)
 348     ->shutdown (application);
 349 }
 350
 351 static void
 352 gtk_application_add_platform_data (GApplication    *application,
 353                                    GVariantBuilder *builder)
 354 {
 355   const gchar *startup_id;
 356
 357   startup_id = getenv ("DESKTOP_STARTUP_ID");
 358
 359   if (startup_id && g_utf8_validate (startup_id, -1, NULL))
 360     g_variant_builder_add (builder, "{sv}", "desktop-startup-id",
 361                            g_variant_new_string (startup_id));
 362 }
 363
 364 static void
 365 gtk_application_before_emit (GApplication *application,
 366                              GVariant     *platform_data)
 367 {
 368   GVariantIter iter;
 369   const gchar *key;
 370   GVariant *value;
 371
 372   g_variant_iter_init (&iter, platform_data);
 373   while (g_variant_iter_loop (&iter, "{&sv}", &key, &value))
 374     {
 375 #ifdef GDK_WINDOWING_X11
 376       if (strcmp (key, "desktop-startup-id") == 0)
 377         {
 378           GdkDisplay *display;
 379           const gchar *id;
 380
 381           display = gdk_display_get_default ();
 382           id = g_variant_get_string (value, NULL);
 383           if (GDK_IS_X11_DISPLAY (display))
 384             gdk_x11_display_set_startup_notification_id (display, id);
 385        }
 386 #endif
 387     }
 388 }
 389
 390 static void
 391 gtk_application_after_emit (GApplication *application,
 392                             GVariant     *platform_data)
 393 {
 394   gdk_notify_startup_complete ();
 395 }
 396
 397 static void
 398 gtk_application_init (GtkApplication *application)
 399 {
 400   application->priv = G_TYPE_INSTANCE_GET_PRIVATE (application,
 401                                                    GTK_TYPE_APPLICATION,
 402                                                    GtkApplicationPrivate);
 403 }
 404
 405 static void
 406 gtk_application_window_added (GtkApplication *application,
 407                               GtkWindow      *window)
 408 {
 409   GtkApplicationPrivate *priv = application->priv;
 410
 411   priv->windows = g_list_prepend (priv->windows, window);
 412   gtk_window_set_application (window, application);
 413   g_application_hold (G_APPLICATION (application));
 414
 415   g_signal_connect (window, "focus-in-event",
 416                     G_CALLBACK (gtk_application_focus_in_event_cb),
 417                     application);
 418
 419 #ifdef GDK_WINDOWING_X11
 420   gtk_application_window_added_x11 (application, window);
 421 #endif
 422 }
 423
 424 static void
 425 gtk_application_window_removed (GtkApplication *application,
 426                                 GtkWindow      *window)
 427 {
 428   GtkApplicationPrivate *priv = application->priv;
 429
 430 #ifdef GDK_WINDOWING_X11
 431   gtk_application_window_removed_x11 (application, window);
 432 #endif
 433
 434   g_signal_handlers_disconnect_by_func (window,
 435                                         gtk_application_focus_in_event_cb,
 436                                         application);
 437
 438   g_application_release (G_APPLICATION (application));
 439   priv->windows = g_list_remove (priv->windows, window);
 440   gtk_window_set_application (window, NULL);
 441 }
 442
 443 static void
 444 extract_accel_from_menu_item (GMenuModel     *model,
 445                               gint            item,
 446                               GtkApplication *app)
 447 {
 448   GMenuAttributeIter *iter;
 449   const gchar *key;
 450   GVariant *value;
 451   const gchar *accel = NULL;
 452   const gchar *action = NULL;
 453   GVariant *target = NULL;
 454
 455   iter = g_menu_model_iterate_item_attributes (model, item);
 456   while (g_menu_attribute_iter_get_next (iter, &key, &value))
 457     {
 458       if (g_str_equal (key, "action") && g_variant_is_of_type (value, G_VARIANT_TYPE_STRING))
 459         action = g_variant_get_string (value, NULL);
 460       else if (g_str_equal (key, "accel") && g_variant_is_of_type (value, G_VARIANT_TYPE_STRING))
 461         accel = g_variant_get_string (value, NULL);
 462       else if (g_str_equal (key, "target"))
 463         target = g_variant_ref (value);
 464       g_variant_unref (value);
 465     }
 466   g_object_unref (iter);
 467
 468   if (accel && action)
 469     gtk_application_add_accelerator (app, accel, action, target);
 470
 471   if (target)
 472     g_variant_unref (target);
 473 }
 474
 475 static void
 476 extract_accels_from_menu (GMenuModel     *model,
 477                           GtkApplication *app)
 478 {
 479   gint i;
 480   GMenuLinkIter *iter;
 481   const gchar *key;
 482   GMenuModel *m;
 483
 484   for (i = 0; i < g_menu_model_get_n_items (model); i++)
 485     {
 486       extract_accel_from_menu_item (model, i, app);
 487
 488       iter = g_menu_model_iterate_item_links (model, i);
 489       while (g_menu_link_iter_get_next (iter, &key, &m))
 490         {
 491           extract_accels_from_menu (m, app);
 492           g_object_unref (m);
 493         }
 494       g_object_unref (iter);
 495     }
 496 }
 497
 498 static void
 499 gtk_application_notify (GObject    *object,
 500                         GParamSpec *pspec)
 501 {
 502   if (strcmp (pspec->name, "app-menu") == 0 ||
 503       strcmp (pspec->name, "menubar") == 0)
 504     {
 505       GMenuModel *model;
 506       g_object_get (object, pspec->name, &model, NULL);
 507       if (model)
 508         {
 509           extract_accels_from_menu (model, GTK_APPLICATION (object));
 510           g_object_unref (model);
 511         }
 512     }
 513
 514   if (G_OBJECT_CLASS (gtk_application_parent_class)->notify)
 515     G_OBJECT_CLASS (gtk_application_parent_class)->notify (object, pspec);
 516 }
 517
 518 static void
 519 gtk_application_class_init (GtkApplicationClass *class)
 520 {
 521   GObjectClass *object_class = G_OBJECT_CLASS (class);
 522   GApplicationClass *application_class = G_APPLICATION_CLASS (class);
 523
 524   object_class->notify = gtk_application_notify;
 525
 526   application_class->add_platform_data = gtk_application_add_platform_data;
 527   application_class->before_emit = gtk_application_before_emit;
 528   application_class->after_emit = gtk_application_after_emit;
 529   application_class->startup = gtk_application_startup;
 530   application_class->shutdown = gtk_application_shutdown;
 531
 532   class->window_added = gtk_application_window_added;
 533   class->window_removed = gtk_application_window_removed;
 534
 535   g_type_class_add_private (class, sizeof (GtkApplicationPrivate));
 536
 537   /**
 538    * GtkApplication::window-added:
 539    * @application: the #GtkApplication which emitted the signal
 540    * @window: the newly-added #GtkWindow
 541    *
 542    * Emitted when a #GtkWindow is added to @application through
 543    * gtk_application_add_window().
 544    *
 545    * Since: 3.2
 546    */
 547   gtk_application_signals[WINDOW_ADDED] =
 548     g_signal_new ("window-added", GTK_TYPE_APPLICATION, G_SIGNAL_RUN_FIRST,
 549                   G_STRUCT_OFFSET (GtkApplicationClass, window_added),
 550                   NULL, NULL,
 551                   g_cclosure_marshal_VOID__OBJECT,
 552                   G_TYPE_NONE, 1, GTK_TYPE_WINDOW);
 553
 554   /**
 555    * GtkApplication::window-removed:
 556    * @application: the #GtkApplication which emitted the signal
 557    * @window: the #GtkWindow that is being removed
 558    *
 559    * Emitted when a #GtkWindow is removed from @application,
 560    * either as a side-effect of being destroyed or explicitly
 561    * through gtk_application_remove_window().
 562    *
 563    * Since: 3.2
 564    */
 565   gtk_application_signals[WINDOW_REMOVED] =
 566     g_signal_new ("window-removed", GTK_TYPE_APPLICATION, G_SIGNAL_RUN_FIRST,
 567                   G_STRUCT_OFFSET (GtkApplicationClass, window_removed),
 568                   NULL, NULL,
 569                   g_cclosure_marshal_VOID__OBJECT,
 570                   G_TYPE_NONE, 1, GTK_TYPE_WINDOW);
 571 }
 572
 573 /**
 574  * gtk_application_new:
 575  * @application_id: the application id
 576  * @flags: the application flags
 577  *
 578  * Creates a new #GtkApplication instance.
 579  *
 580  * This function calls g_type_init() for you. gtk_init() is called
 581  * as soon as the application gets registered as the primary instance.
 582  *
 583  * The application id must be valid. See g_application_id_is_valid().
 584  *
 585  * Returns: a new #GtkApplication instance
 586  */
 587 GtkApplication *
 588 gtk_application_new (const gchar       *application_id,
 589                      GApplicationFlags  flags)
 590 {
 591   g_return_val_if_fail (g_application_id_is_valid (application_id), NULL);
 592
 593   g_type_init ();
 594
 595   return g_object_new (GTK_TYPE_APPLICATION,
 596                        "application-id", application_id,
 597                        "flags", flags,
 598                        NULL);
 599 }
 600
 601 /**
 602  * gtk_application_add_window:
 603  * @application: a #GtkApplication
 604  * @window: a #GtkWindow
 605  *
 606  * Adds a window from @application.
 607  *
 608  * This call is equivalent to setting the #GtkWindow:application
 609  * property of @window to @application.
 610  *
 611  * Normally, the connection between the application and the window
 612  * will remain until the window is destroyed, but you can explicitly
 613  * remove it with gtk_application_remove_window().
 614  *
 615  * GTK+ will keep the application running as long as it has
 616  * any windows.
 617  *
 618  * Since: 3.0
 619  **/
 620 void
 621 gtk_application_add_window (GtkApplication *application,
 622                             GtkWindow      *window)
 623 {
 624   g_return_if_fail (GTK_IS_APPLICATION (application));
 625
 626   if (!g_list_find (application->priv->windows, window))
 627     g_signal_emit (application,
 628                    gtk_application_signals[WINDOW_ADDED], 0, window);
 629 }
 630
 631 /**
 632  * gtk_application_remove_window:
 633  * @application: a #GtkApplication
 634  * @window: a #GtkWindow
 635  *
 636  * Remove a window from @application.
 637  *
 638  * If @window belongs to @application then this call is equivalent to
 639  * setting the #GtkWindow:application property of @window to
 640  * %NULL.
 641  *
 642  * The application may stop running as a result of a call to this
 643  * function.
 644  *
 645  * Since: 3.0
 646  **/
 647 void
 648 gtk_application_remove_window (GtkApplication *application,
 649                                GtkWindow      *window)
 650 {
 651   g_return_if_fail (GTK_IS_APPLICATION (application));
 652
 653   if (g_list_find (application->priv->windows, window))
 654     g_signal_emit (application,
 655                    gtk_application_signals[WINDOW_REMOVED], 0, window);
 656 }
 657
 658 /**
 659  * gtk_application_get_windows:
 660  * @application: a #GtkApplication
 661  *
 662  * Gets a list of the #GtkWindows associated with @application.
 663  *
 664  * The list is sorted by most recently focused window, such that the first
 665  * element is the currently focused window. (Useful for choosing a parent
 666  * for a transient window.)
 667  *
 668  * The list that is returned should not be modified in any way. It will
 669  * only remain valid until the next focus change or window creation or
 670  * deletion.
 671  *
 672  * Returns: (element-type GtkWindow) (transfer none): a #GList of #GtkWindow
 673  *
 674  * Since: 3.0
 675  **/
 676 GList *
 677 gtk_application_get_windows (GtkApplication *application)
 678 {
 679   g_return_val_if_fail (GTK_IS_APPLICATION (application), NULL);
 680
 681   return application->priv->windows;
 682 }
 683
 684 /**
 685  * gtk_application_add_accelerator:
 686  * @application: a #GtkApplication
 687  * @accelerator: accelerator string
 688  * @action_name: the name of the action to activate
 689  * @parameter: (allow-none): parameter to pass when activating the action,
 690  *   or %NULL if the action does not accept an activation parameter
 691  *
 692  * Installs an accelerator that will cause the named action
 693  * to be activated when the key combination specificed by @accelerator
 694  * is pressed.
 695  *
 696  * @accelerator must be a string that can be parsed by
 697  * gtk_accelerator_parse(), e.g. "<Primary>q" or "<Control><Alt>p".
 698  *
 699  * @action_name must be the name of an action as it would be used
 700  * in the app menu, i.e. actions that have been added to the application
 701  * are referred to with an "app." prefix, and window-specific actions
 702  * with a "win." prefix.
 703  *
 704  * GtkApplication also extracts accelerators out of 'accel' attributes
 705  * in the #GMenuModels passed to g_application_set_app_menu() and
 706  * g_application_set_menubar(), which is usually more convenient
 707  * than calling this function for each accelerator.
 708  *
 709  * Since: 3.4
 710  */
 711 void
 712 gtk_application_add_accelerator (GtkApplication *application,
 713                                  const gchar    *accelerator,
 714                                  const gchar    *action_name,
 715                                  GVariant       *parameter)
 716 {
 717   gchar *accel_path;
 718   guint accel_key;
 719   GdkModifierType accel_mods;
 720
 721   g_return_if_fail (GTK_IS_APPLICATION (application));
 722
 723   /* Call this here, since gtk_init() is only getting called in startup() */
 724   _gtk_accel_map_init ();
 725
 726   gtk_accelerator_parse (accelerator, &accel_key, &accel_mods);
 727
 728   if (accel_key == 0)
 729     {
 730       g_warning ("Failed to parse accelerator: '%s'\n", accelerator);
 731       return;
 732     }
 733
 734   accel_path = _gtk_accel_path_for_action (action_name, parameter);
 735
 736   if (gtk_accel_map_lookup_entry (accel_path, NULL))
 737     gtk_accel_map_change_entry (accel_path, accel_key, accel_mods, TRUE);
 738   else
 739     gtk_accel_map_add_entry (accel_path, accel_key, accel_mods);
 740
 741   g_free (accel_path);
 742 }
 743
 744 /**
 745  * gtk_application_remove_accelerator:
 746  * @application: a #GtkApplication
 747  * @action_name: the name of the action to activate
 748  * @parameter: (allow-none): parameter to pass when activating the action,
 749  *   or %NULL if the action does not accept an activation parameter
 750  *
 751  * Removes an accelerator that has been previously added
 752  * with gtk_application_add_accelerator().
 753  *
 754  * Since: 3.4
 755  */
 756 void
 757 gtk_application_remove_accelerator (GtkApplication *application,
 758                                     const gchar    *action_name,
 759                                     GVariant       *parameter)
 760 {
 761   gchar *accel_path;
 762
 763   g_return_if_fail (GTK_IS_APPLICATION (application));
 764
 765   accel_path = _gtk_accel_path_for_action (action_name, parameter);
 766
 767   if (!gtk_accel_map_lookup_entry (accel_path, NULL))
 768     {
 769       g_warning ("No accelerator found for '%s'\n", accel_path);
 770       g_free (accel_path);
 771       return;
 772     }
 773
 774   gtk_accel_map_change_entry (accel_path, 0, 0, FALSE);
 775   g_free (accel_path);
 776 }