/*
* Copyright © 2010 Codethink Limited
*
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as published
- * by the Free Software Foundation; either version 2 of the licence or (at
- * your option) any later version.
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
#include "gapplicationimpl.h"
#include "gactiongroup.h"
#include "gactionmap.h"
-#include "gmenumodel.h"
#include "gsettings.h"
#include "gnotification-private.h"
#include "gnotificationbackend.h"
#include "gfile.h"
#include "glibintl.h"
+#include "gmarshal-internal.h"
#include <string.h>
* arguments are passed through platform communication to the already
* running program. The already running instance of the program is
* called the "primary instance"; for non-unique applications this is
- * the always the current instance. On Linux, the D-Bus session bus
+ * always the current instance. On Linux, the D-Bus session bus
* is used for communication.
*
* The use of #GApplication differs from some other commonly-used
* instance and g_application_run() promptly returns. See the code
* examples below.
*
- * If used, the expected form of an application identifier is very close
- * to that of of a
- * [DBus bus name](http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface).
- * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
+ * If used, the expected form of an application identifier is the same as
+ * that of of a
+ * [D-Bus well-known bus name](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus).
+ * Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`,
+ * `org._7_zip.Archiver`.
* For details on valid application identifiers, see g_application_id_is_valid().
*
* On Linux, the application identifier is claimed as a well-known bus name
* initialization for all of these in a single place.
*
* Regardless of which of these entry points is used to start the
- * application, GApplication passes some "platform data from the
+ * application, GApplication passes some ‘platform data’ from the
* launching instance to the primary instance, in the form of a
* #GVariant dictionary mapping strings to variants. To use platform
* data, override the @before_emit or @after_emit virtual functions
*/
/**
+ * GApplication:
+ *
+ * #GApplication is an opaque data structure and can only be accessed
+ * using the following functions.
+ * Since: 2.28
+ */
+
+/**
* GApplicationClass:
* @startup: invoked on the primary instance immediately after registration
* @shutdown: invoked only on the registered primary instance immediately
* @open: invoked on the primary instance when there are files to open
* @command_line: invoked on the primary instance when a command-line is
* not handled locally
- * @local_command_line: invoked (locally) when the process has been invoked
- * via commandline execution (as opposed to, say, D-Bus activation - which
- * is not currently supported by GApplication). The virtual function has
- * the chance to inspect (and possibly replace) the list of command line
- * arguments. See g_application_run() for more information.
+ * @local_command_line: invoked (locally). The virtual function has the chance
+ * to inspect (and possibly replace) command line arguments. See
+ * g_application_run() for more information. Also see the
+ * #GApplication::handle-local-options signal, which is a simpler
+ * alternative to handling some commandline options locally
* @before_emit: invoked on the primary instance before 'activate', 'open',
* 'command-line' or any action invocation, gets the 'platform data' from
* the calling instance
* If this function returns %TRUE, registration will proceed; otherwise
* registration will abort. Since: 2.34
* @dbus_unregister: invoked locally during unregistration, if the application
- * is using its D-Bus backend. Use this to undo anything done by the
- * @dbus_register vfunc. Since: 2.34
+ * is using its D-Bus backend. Use this to undo anything done by
+ * the @dbus_register vfunc. Since: 2.34
+ * @handle_local_options: invoked locally after the parsing of the commandline
+ * options has occurred. Since: 2.40
+ * @name_lost: invoked when another instance is taking over the name. Since: 2.60
*
* Virtual function table for #GApplication.
*
gchar *resource_path;
GActionGroup *actions;
- GMenuModel *app_menu;
- GMenuModel *menubar;
guint inactivity_timeout_id;
guint inactivity_timeout;
GSList *option_groups;
GHashTable *packed_options;
gboolean options_parsed;
+ gchar *parameter_string;
+ gchar *summary;
+ gchar *description;
/* Allocated option strings, from g_application_add_main_option() */
GSList *option_strings;
PROP_IS_REGISTERED,
PROP_IS_REMOTE,
PROP_INACTIVITY_TIMEOUT,
- PROP_ACTION_GROUP
+ PROP_ACTION_GROUP,
+ PROP_IS_BUSY
};
enum
SIGNAL_ACTION,
SIGNAL_COMMAND_LINE,
SIGNAL_HANDLE_LOCAL_OPTIONS,
+ SIGNAL_NAME_LOST,
NR_SIGNALS
};
GError **error)
{
gboolean become_service = FALSE;
+ gchar *app_id = NULL;
+ gboolean replace = FALSE;
GVariantDict *dict = NULL;
GOptionContext *context;
+ GOptionGroup *gapplication_group;
/* Due to the memory management of GOptionGroup we can only parse
* options once. That's because once you add a group to the
*/
g_return_val_if_fail (!application->priv->options_parsed, NULL);
- context = g_option_context_new (NULL);
+ context = g_option_context_new (application->priv->parameter_string);
+ g_option_context_set_summary (context, application->priv->summary);
+ g_option_context_set_description (context, application->priv->description);
+
+ gapplication_group = g_option_group_new ("gapplication",
+ _("GApplication options"), _("Show GApplication options"),
+ NULL, NULL);
+ g_option_group_set_translation_domain (gapplication_group, GETTEXT_PACKAGE);
+ g_option_context_add_group (context, gapplication_group);
+
+ /* If the application has not registered local options and it has
+ * G_APPLICATION_HANDLES_COMMAND_LINE then we have to assume that
+ * their primary instance commandline handler may want to deal with
+ * the arguments. We must therefore ignore them.
+ *
+ * We must also ignore --help in this case since some applications
+ * will try to handle this from the remote side. See #737869.
+ */
+ if (application->priv->main_options == NULL && (application->priv->flags & G_APPLICATION_HANDLES_COMMAND_LINE))
+ {
+ g_option_context_set_ignore_unknown_options (context, TRUE);
+ g_option_context_set_help_enabled (context, FALSE);
+ }
/* Add the main option group, if it exists */
if (application->priv->main_options)
application->priv->option_groups);
}
- /* If the application has not registered local options and it has
- * G_APPLICATION_HANDLES_COMMAND_LINE then we have to assume that
- * their primary instance commandline handler may want to deal with
- * the arguments. We must therefore ignore them.
- */
- if (application->priv->main_options == NULL && (application->priv->flags & G_APPLICATION_HANDLES_COMMAND_LINE))
- g_option_context_set_ignore_unknown_options (context, TRUE);
-
/* In the case that we are not explicitly marked as a service or a
* launcher then we want to add the "--gapplication-service" option to
* allow the process to be made into a service.
*/
if ((application->priv->flags & (G_APPLICATION_IS_SERVICE | G_APPLICATION_IS_LAUNCHER)) == 0)
{
- GOptionGroup *option_group;
GOptionEntry entries[] = {
{ "gapplication-service", '\0', 0, G_OPTION_ARG_NONE, &become_service,
- N_("Enter GApplication service mode (use from D-Bus service files)") },
+ N_("Enter GApplication service mode (use from D-Bus service files)"), NULL },
{ NULL }
};
- option_group = g_option_group_new ("gapplication",
- _("GApplication options"), _("Show GApplication options"),
- NULL, NULL);
- g_option_group_set_translation_domain (option_group, GETTEXT_PACKAGE);
- g_option_group_add_entries (option_group, entries);
+ g_option_group_add_entries (gapplication_group, entries);
+ }
- g_option_context_add_group (context, option_group);
+ /* Allow overriding the ID if the application allows it */
+ if (application->priv->flags & G_APPLICATION_CAN_OVERRIDE_APP_ID)
+ {
+ GOptionEntry entries[] = {
+ { "gapplication-app-id", '\0', 0, G_OPTION_ARG_STRING, &app_id,
+ N_("Override the application’s ID"), NULL },
+ { NULL }
+ };
+
+ g_option_group_add_entries (gapplication_group, entries);
+ }
+
+ /* Allow replacing if the application allows it */
+ if (application->priv->flags & G_APPLICATION_ALLOW_REPLACEMENT)
+ {
+ GOptionEntry entries[] = {
+ { "gapplication-replace", '\0', 0, G_OPTION_ARG_NONE, &replace,
+ N_("Replace the running instance"), NULL },
+ { NULL }
+ };
+
+ g_option_group_add_entries (gapplication_group, entries);
}
/* Now we parse... */
if (become_service)
application->priv->flags |= G_APPLICATION_IS_SERVICE;
+ /* Check for --gapplication-app-id */
+ if (app_id)
+ g_application_set_application_id (application, app_id);
+
+ /* Check for --gapplication-replace */
+ if (replace)
+ application->priv->flags |= G_APPLICATION_REPLACE;
+
dict = g_variant_dict_new (NULL);
if (application->priv->packed_options)
{
application->priv->options_parsed = TRUE;
g_option_context_free (context);
+ g_free (app_id);
return dict;
}
* consumed, they will no longer be visible to the default handling
* (which treats them as filenames to be opened).
*
+ * It is important to use the proper GVariant format when retrieving
+ * the options with g_variant_dict_lookup():
+ * - for %G_OPTION_ARG_NONE, use `b`
+ * - for %G_OPTION_ARG_STRING, use `&s`
+ * - for %G_OPTION_ARG_INT, use `i`
+ * - for %G_OPTION_ARG_INT64, use `x`
+ * - for %G_OPTION_ARG_DOUBLE, use `d`
+ * - for %G_OPTION_ARG_FILENAME, use `^&ay`
+ * - for %G_OPTION_ARG_STRING_ARRAY, use `^a&s`
+ * - for %G_OPTION_ARG_FILENAME_ARRAY, use `^a&ay`
+ *
* Since: 2.40
*/
void
g_return_if_fail (entries != NULL);
if (!application->priv->main_options)
- application->priv->main_options = g_option_group_new (NULL, NULL, NULL, NULL, NULL);
+ {
+ application->priv->main_options = g_option_group_new (NULL, NULL, NULL, NULL, NULL);
+ g_option_group_set_translation_domain (application->priv->main_options, NULL);
+ }
for (i = 0; entries[i].long_name; i++)
{
g_application_add_main_option (GApplication *application,
const char *long_name,
char short_name,
- gint flags,
+ GOptionFlags flags,
GOptionArg arg,
const char *description,
const char *arg_description)
/**
* g_application_add_option_group:
* @application: the #GApplication
- * @group: a #GOptionGroup
+ * @group: (transfer full): a #GOptionGroup
*
* Adds a #GOptionGroup to the commandline handling of @application.
*
application->priv->option_groups = g_slist_prepend (application->priv->option_groups, group);
}
+/**
+ * g_application_set_option_context_parameter_string:
+ * @application: the #GApplication
+ * @parameter_string: (nullable): a string which is displayed
+ * in the first line of `--help` output, after the usage summary `programname [OPTION...]`.
+ *
+ * Sets the parameter string to be used by the commandline handling of @application.
+ *
+ * This function registers the argument to be passed to g_option_context_new()
+ * when the internal #GOptionContext of @application is created.
+ *
+ * See g_option_context_new() for more information about @parameter_string.
+ *
+ * Since: 2.56
+ */
+void
+g_application_set_option_context_parameter_string (GApplication *application,
+ const gchar *parameter_string)
+{
+ g_return_if_fail (G_IS_APPLICATION (application));
+
+ g_free (application->priv->parameter_string);
+ application->priv->parameter_string = g_strdup (parameter_string);
+}
+
+/**
+ * g_application_set_option_context_summary:
+ * @application: the #GApplication
+ * @summary: (nullable): a string to be shown in `--help` output
+ * before the list of options, or %NULL
+ *
+ * Adds a summary to the @application option context.
+ *
+ * See g_option_context_set_summary() for more information.
+ *
+ * Since: 2.56
+ */
+void
+g_application_set_option_context_summary (GApplication *application,
+ const gchar *summary)
+{
+ g_return_if_fail (G_IS_APPLICATION (application));
+
+ g_free (application->priv->summary);
+ application->priv->summary = g_strdup (summary);
+}
+
+/**
+ * g_application_set_option_context_description:
+ * @application: the #GApplication
+ * @description: (nullable): a string to be shown in `--help` output
+ * after the list of options, or %NULL
+ *
+ * Adds a description to the @application option context.
+ *
+ * See g_option_context_set_description() for more information.
+ *
+ * Since: 2.56
+ */
+void
+g_application_set_option_context_description (GApplication *application,
+ const gchar *description)
+{
+ g_return_if_fail (G_IS_APPLICATION (application));
+
+ g_free (application->priv->description);
+ application->priv->description = g_strdup (description);
+
+}
+
+
/* vfunc defaults {{{1 */
static void
g_application_real_before_emit (GApplication *application,
if (!options)
{
g_printerr ("%s\n", error->message);
+ g_error_free (error);
*exit_status = 1;
return TRUE;
}
{
}
+static gboolean
+g_application_real_name_lost (GApplication *application)
+{
+ g_application_quit (application);
+ return TRUE;
+}
+
/* GObject implementation stuff {{{1 */
static void
g_application_set_property (GObject *object,
/**
* g_application_set_action_group:
* @application: a #GApplication
- * @action_group: (allow-none): a #GActionGroup, or %NULL
+ * @action_group: (nullable): a #GActionGroup, or %NULL
*
* This used to be how actions were associated with a #GApplication.
* Now there is #GActionMap for that.
g_application_get_inactivity_timeout (application));
break;
+ case PROP_IS_BUSY:
+ g_value_set_boolean (value, g_application_get_is_busy (application));
+ break;
+
default:
g_assert_not_reached ();
}
}
static void
+g_application_dispose (GObject *object)
+{
+ GApplication *application = G_APPLICATION (object);
+
+ if (application->priv->impl != NULL &&
+ G_APPLICATION_GET_CLASS (application)->dbus_unregister != g_application_real_dbus_unregister)
+ {
+ static gboolean warned;
+
+ if (!warned)
+ {
+ g_warning ("Your application did not unregister from D-Bus before destruction. "
+ "Consider using g_application_run().");
+ }
+
+ warned = TRUE;
+ }
+
+ G_OBJECT_CLASS (g_application_parent_class)->dispose (object);
+}
+
+static void
g_application_finalize (GObject *object)
{
GApplication *application = G_APPLICATION (object);
- g_slist_free_full (application->priv->option_groups, (GDestroyNotify) g_option_group_free);
+ if (application->priv->inactivity_timeout_id)
+ g_source_remove (application->priv->inactivity_timeout_id);
+
+ g_slist_free_full (application->priv->option_groups, (GDestroyNotify) g_option_group_unref);
if (application->priv->main_options)
- g_option_group_free (application->priv->main_options);
+ g_option_group_unref (application->priv->main_options);
if (application->priv->packed_options)
- {
- g_slist_free_full (application->priv->option_strings, g_free);
- g_hash_table_unref (application->priv->packed_options);
- }
+ g_hash_table_unref (application->priv->packed_options);
+
+ g_free (application->priv->parameter_string);
+ g_free (application->priv->summary);
+ g_free (application->priv->description);
+
+ g_slist_free_full (application->priv->option_strings, g_free);
+
if (application->priv->impl)
g_application_impl_destroy (application->priv->impl);
g_free (application->priv->id);
if (application->priv->actions)
g_object_unref (application->priv->actions);
+ g_clear_object (&application->priv->remote_actions);
+
if (application->priv->notifications)
g_object_unref (application->priv->notifications);
+ g_free (application->priv->resource_path);
+
G_OBJECT_CLASS (g_application_parent_class)
->finalize (object);
}
value = g_value_get_int (handler_return);
g_value_set_int (return_accu, value);
- return value >= 0;
+ return value < 0;
}
static void
GObjectClass *object_class = G_OBJECT_CLASS (class);
object_class->constructed = g_application_constructed;
+ object_class->dispose = g_application_dispose;
object_class->finalize = g_application_finalize;
object_class->get_property = g_application_get_property;
object_class->set_property = g_application_set_property;
class->add_platform_data = g_application_real_add_platform_data;
class->dbus_register = g_application_real_dbus_register;
class->dbus_unregister = g_application_real_dbus_unregister;
+ class->name_lost = g_application_real_name_lost;
g_object_class_install_property (object_class, PROP_APPLICATION_ID,
g_param_spec_string ("application-id",
G_PARAM_DEPRECATED | G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS));
/**
+ * GApplication:is-busy:
+ *
+ * Whether the application is currently marked as busy through
+ * g_application_mark_busy() or g_application_bind_busy_property().
+ *
+ * Since: 2.44
+ */
+ g_object_class_install_property (object_class, PROP_IS_BUSY,
+ g_param_spec_boolean ("is-busy",
+ P_("Is busy"),
+ P_("If this application is currently marked busy"),
+ FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
+
+ /**
* GApplication::startup:
* @application: the application
*
* after registration. See g_application_register().
*/
g_application_signals[SIGNAL_STARTUP] =
- g_signal_new ("startup", G_TYPE_APPLICATION, G_SIGNAL_RUN_FIRST,
+ g_signal_new (I_("startup"), G_TYPE_APPLICATION, G_SIGNAL_RUN_FIRST,
G_STRUCT_OFFSET (GApplicationClass, startup),
- NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
+ NULL, NULL, NULL, G_TYPE_NONE, 0);
/**
* GApplication::shutdown:
* immediately after the main loop terminates.
*/
g_application_signals[SIGNAL_SHUTDOWN] =
- g_signal_new ("shutdown", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
+ g_signal_new (I_("shutdown"), G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GApplicationClass, shutdown),
- NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
+ NULL, NULL, NULL, G_TYPE_NONE, 0);
/**
* GApplication::activate:
* activation occurs. See g_application_activate().
*/
g_application_signals[SIGNAL_ACTIVATE] =
- g_signal_new ("activate", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
+ g_signal_new (I_("activate"), G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GApplicationClass, activate),
- NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
+ NULL, NULL, NULL, G_TYPE_NONE, 0);
/**
* files to open. See g_application_open() for more information.
*/
g_application_signals[SIGNAL_OPEN] =
- g_signal_new ("open", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
+ g_signal_new (I_("open"), G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GApplicationClass, open),
- NULL, NULL, NULL,
+ NULL, NULL,
+ _g_cclosure_marshal_VOID__POINTER_INT_STRING,
G_TYPE_NONE, 3, G_TYPE_POINTER, G_TYPE_INT, G_TYPE_STRING);
+ g_signal_set_va_marshaller (g_application_signals[SIGNAL_OPEN],
+ G_TYPE_FROM_CLASS (class),
+ _g_cclosure_marshal_VOID__POINTER_INT_STRINGv);
/**
* GApplication::command-line:
* process. See g_application_command_line_set_exit_status().
*/
g_application_signals[SIGNAL_COMMAND_LINE] =
- g_signal_new ("command-line", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
+ g_signal_new (I_("command-line"), G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GApplicationClass, command_line),
g_signal_accumulator_first_wins, NULL,
- NULL,
+ _g_cclosure_marshal_INT__OBJECT,
G_TYPE_INT, 1, G_TYPE_APPLICATION_COMMAND_LINE);
+ g_signal_set_va_marshaller (g_application_signals[SIGNAL_COMMAND_LINE],
+ G_TYPE_FROM_CLASS (class),
+ _g_cclosure_marshal_INT__OBJECTv);
/**
* GApplication::handle-local-options:
* decide to perform certain actions, including direct local handling
* (which may be useful for options like --version).
*
- * If the options have been "handled" then a non-negative value should
- * be returned. In this case, the return value is the exit status: 0
- * for success and a positive value for failure. -1 means to continue
- * normal processing.
- *
* In the event that the application is marked
* %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will
- * send the @option dictionary to the primary instance where it can be
- * read with g_application_command_line_get_options(). The signal
+ * send the @options dictionary to the primary instance where it can be
+ * read with g_application_command_line_get_options_dict(). The signal
* handler can modify the dictionary before returning, and the
* modified dictionary will be sent.
*
* capabilities than what is provided here, but this should not
* normally be required.
*
+ * Returns: an exit code. If you have handled your options and want
+ * to exit the process, return a non-negative option, 0 for success,
+ * and a positive value for failure. To continue, return -1 to let
+ * the default option processing continue.
+ *
* Since: 2.40
**/
g_application_signals[SIGNAL_HANDLE_LOCAL_OPTIONS] =
- g_signal_new ("handle-local-options", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
+ g_signal_new (I_("handle-local-options"), G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GApplicationClass, handle_local_options),
- g_application_handle_local_options_accumulator, NULL, NULL,
+ g_application_handle_local_options_accumulator, NULL,
+ _g_cclosure_marshal_INT__BOXED,
G_TYPE_INT, 1, G_TYPE_VARIANT_DICT);
+ g_signal_set_va_marshaller (g_application_signals[SIGNAL_HANDLE_LOCAL_OPTIONS],
+ G_TYPE_FROM_CLASS (class),
+ _g_cclosure_marshal_INT__BOXEDv);
+ /**
+ * GApplication::name-lost:
+ * @application: the application
+ *
+ * The ::name-lost signal is emitted only on the registered primary instance
+ * when a new instance has taken over. This can only happen if the application
+ * is using the %G_APPLICATION_ALLOW_REPLACEMENT flag.
+ *
+ * The default handler for this signal calls g_application_quit().
+ *
+ * Returns: %TRUE if the signal has been handled
+ *
+ * Since: 2.60
+ */
+ g_application_signals[SIGNAL_NAME_LOST] =
+ g_signal_new (I_("name-lost"), G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
+ G_STRUCT_OFFSET (GApplicationClass, name_lost),
+ g_signal_accumulator_true_handled, NULL,
+ _g_cclosure_marshal_BOOLEAN__VOID,
+ G_TYPE_BOOLEAN, 0);
+ g_signal_set_va_marshaller (g_application_signals[SIGNAL_NAME_LOST],
+ G_TYPE_FROM_CLASS (class),
+ _g_cclosure_marshal_BOOLEAN__VOIDv);
}
/* Application ID validity {{{1 */
* A valid ID is required for calls to g_application_new() and
* g_application_set_application_id().
*
+ * Application identifiers follow the same format as
+ * [D-Bus well-known bus names](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus).
* For convenience, the restrictions on application identifiers are
* reproduced here:
*
- * - Application identifiers must contain only the ASCII characters
- * "[A-Z][a-z][0-9]_-." and must not begin with a digit.
+ * - Application identifiers are composed of 1 or more elements separated by a
+ * period (`.`) character. All elements must contain at least one character.
*
- * - Application identifiers must contain at least one '.' (period)
- * character (and thus at least three elements).
+ * - Each element must only contain the ASCII characters `[A-Z][a-z][0-9]_-`,
+ * with `-` discouraged in new application identifiers. Each element must not
+ * begin with a digit.
*
- * - Application identifiers must not begin or end with a '.' (period)
- * character.
+ * - Application identifiers must contain at least one `.` (period) character
+ * (and thus at least two elements).
*
- * - Application identifiers must not contain consecutive '.' (period)
- * characters.
+ * - Application identifiers must not begin with a `.` (period) character.
*
* - Application identifiers must not exceed 255 characters.
*
+ * Note that the hyphen (`-`) character is allowed in application identifiers,
+ * but is problematic or not allowed in various specifications and APIs that
+ * refer to D-Bus, such as
+ * [Flatpak application IDs](http://docs.flatpak.org/en/latest/introduction.html#identifiers),
+ * the
+ * [`DBusActivatable` interface in the Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus),
+ * and the convention that an application's "main" interface and object path
+ * resemble its application identifier and bus name. To avoid situations that
+ * require special-case handling, it is recommended that new application
+ * identifiers consistently replace hyphens with underscores.
+ *
+ * Like D-Bus interface names, application identifiers should start with the
+ * reversed DNS domain name of the author of the interface (in lower-case), and
+ * it is conventional for the rest of the application identifier to consist of
+ * words run together, with initial capital letters.
+ *
+ * As with D-Bus interface names, if the author's DNS domain name contains
+ * hyphen/minus characters they should be replaced by underscores, and if it
+ * contains leading digits they should be escaped by prepending an underscore.
+ * For example, if the owner of 7-zip.org used an application identifier for an
+ * archiving application, it might be named `org._7_zip.Archiver`.
+ *
* Returns: %TRUE if @application_id is valid
*/
gboolean
g_application_id_is_valid (const gchar *application_id)
{
- gsize len;
- gboolean allow_dot;
- gboolean has_dot;
-
- len = strlen (application_id);
-
- if (len > 255)
- return FALSE;
-
- if (!g_ascii_isalpha (application_id[0]))
- return FALSE;
-
- if (application_id[len-1] == '.')
- return FALSE;
-
- application_id++;
- allow_dot = TRUE;
- has_dot = FALSE;
- for (; *application_id; application_id++)
- {
- if (g_ascii_isalnum (*application_id) ||
- (*application_id == '-') ||
- (*application_id == '_'))
- {
- allow_dot = TRUE;
- }
- else if (allow_dot && *application_id == '.')
- {
- has_dot = TRUE;
- allow_dot = FALSE;
- }
- else
- return FALSE;
- }
-
- if (!has_dot)
- return FALSE;
-
- return TRUE;
+ return g_dbus_is_name (application_id) &&
+ !g_dbus_is_unique_name (application_id);
}
/* Public Constructor {{{1 */
/**
* g_application_new:
- * @application_id: (allow-none): the application id
+ * @application_id: (nullable): the application id
* @flags: the application flags
*
* Creates a new #GApplication instance.
*
* Gets the unique identifier for @application.
*
- * Returns: the identifier for @application, owned by @application
+ * Returns: (nullable): the identifier for @application, owned by @application
*
* Since: 2.28
**/
/**
* g_application_set_application_id:
* @application: a #GApplication
- * @application_id: (allow-none): the identifier for @application
+ * @application_id: (nullable): the identifier for @application
*
* Sets the unique identifier for @application.
*
*
* Changing the resource base path once the application is running is
* not recommended. The point at which the resource path is consulted
- * for forming paths for various purposes is unspecified.
+ * for forming paths for various purposes is unspecified. When writing
+ * a sub-class of #GApplication you should either set the
+ * #GApplication:resource-base-path property at construction time, or call
+ * this function during the instance initialization. Alternatively, you
+ * can call this function in the #GApplicationClass.startup virtual function,
+ * before chaining up to the parent implementation.
*
* Since: 2.42
*/
void
g_application_set_resource_base_path (GApplication *application,
- const gchar *resource_path)
+ const gchar *resource_path)
{
g_return_if_fail (G_IS_APPLICATION (application));
g_return_if_fail (resource_path == NULL || g_str_has_prefix (resource_path, "/"));
* This function must not be called before the application has been
* registered. See g_application_get_is_registered().
*
- * Returns: (transfer none): a #GDBusConnection, or %NULL
+ * Returns: (nullable) (transfer none): a #GDBusConnection, or %NULL
*
* Since: 2.34
**/
* This function must not be called before the application has been
* registered. See g_application_get_is_registered().
*
- * Returns: the object path, or %NULL
+ * Returns: (nullable): the object path, or %NULL
*
* Since: 2.34
**/
/**
* g_application_register:
* @application: a #GApplication
- * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @cancellable: (nullable): a #GCancellable, or %NULL
* @error: a pointer to a NULL #GError, or %NULL
*
* Attempts registration of the application.
* g_application_run:
* @application: a #GApplication
* @argc: the argc from main() (or 0 if @argv is %NULL)
- * @argv: (array length=argc) (allow-none): the argv from main(), or %NULL
+ * @argv: (array length=argc) (element-type filename) (nullable):
+ * the argv from main(), or %NULL
*
* Runs the application.
*
* use.
*
* This function sets the prgname (g_set_prgname()), if not already set,
- * to the basename of argv[0]. Since 2.38, if %G_APPLICATION_IS_SERVICE
- * is specified, the prgname is set to the application ID. The main
- * impact of this is is that the wmclass of windows created by Gtk+ will
- * be set accordingly, which helps the window manager determine which
- * application is showing the window.
+ * to the basename of argv[0].
+ *
+ * Much like g_main_loop_run(), this function will acquire the main context
+ * for the duration that the application is running.
*
* Since 2.40, applications that are not explicitly flagged as services
* or launchers (ie: neither %G_APPLICATION_IS_SERVICE or
{
gchar **arguments;
int status;
+ GMainContext *context;
+ gboolean acquired_context;
g_return_val_if_fail (G_IS_APPLICATION (application), 1);
g_return_val_if_fail (argc == 0 || argv != NULL, 1);
g_return_val_if_fail (!application->priv->must_quit_now, 1);
#ifdef G_OS_WIN32
- arguments = g_win32_get_command_line ();
+ {
+ gint new_argc = 0;
+
+ arguments = g_win32_get_command_line ();
+
+ /*
+ * CommandLineToArgvW(), which is called by g_win32_get_command_line(),
+ * pulls in the whole command line that is used to call the program. This is
+ * fine in cases where the program is a .exe program, but in the cases where the
+ * program is a called via a script, such as PyGObject's gtk-demo.py, which is normally
+ * called using 'python gtk-demo.py' on Windows, the program name (argv[0])
+ * returned by g_win32_get_command_line() will not be the argv[0] that ->local_command_line()
+ * would expect, causing the program to fail with "This application can not open files."
+ */
+ new_argc = g_strv_length (arguments);
+
+ if (new_argc > argc)
+ {
+ gint i;
+
+ for (i = 0; i < new_argc - argc; i++)
+ g_free (arguments[i]);
+
+ memmove (&arguments[0],
+ &arguments[new_argc - argc],
+ sizeof (arguments[0]) * (argc + 1));
+ }
+ }
+#elif defined(__APPLE__)
+ {
+ gint i, j;
+
+ /*
+ * OSX adds an unexpected parameter on the format -psn_X_XXXXXX
+ * when opening the application using Launch Services. In order
+ * to avoid that GOption fails to parse this parameter we just
+ * skip it if it was provided.
+ * See: https://gitlab.gnome.org/GNOME/glib/issues/1784
+ */
+ arguments = g_new (gchar *, argc + 1);
+ for (i = 0, j = 0; i < argc; i++)
+ {
+ if (!g_str_has_prefix (argv[i], "-psn_"))
+ {
+ arguments[j] = g_strdup (argv[i]);
+ j++;
+ }
+ }
+ arguments[j] = NULL;
+ }
#else
{
gint i;
}
#endif
- if (g_get_prgname () == NULL)
+ if (g_get_prgname () == NULL && argc > 0)
{
- if (application->priv->flags & G_APPLICATION_IS_SERVICE)
- {
- g_set_prgname (application->priv->id);
- }
- else if (argc > 0)
- {
- gchar *prgname;
+ gchar *prgname;
- prgname = g_path_get_basename (argv[0]);
- g_set_prgname (prgname);
- g_free (prgname);
- }
+ prgname = g_path_get_basename (argv[0]);
+ g_set_prgname (prgname);
+ g_free (prgname);
}
+ context = g_main_context_default ();
+ acquired_context = g_main_context_acquire (context);
+ g_return_val_if_fail (acquired_context, 0);
+
if (!G_APPLICATION_GET_CLASS (application)
->local_command_line (application, &arguments, &status))
{
if (application->priv->must_quit_now)
break;
- g_main_context_iteration (NULL, TRUE);
+ g_main_context_iteration (context, TRUE);
status = 0;
}
}
if (application->priv->impl)
- g_application_impl_flush (application->priv->impl);
+ {
+ g_application_impl_flush (application->priv->impl);
+ g_application_impl_destroy (application->priv->impl);
+ application->priv->impl = NULL;
+ }
g_settings_sync ();
+ if (!application->priv->must_quit_now)
+ while (g_main_context_iteration (context, FALSE))
+ ;
+
+ g_main_context_release (context);
+
return status;
}
*
* If there is no default application then %NULL is returned.
*
- * Returns: (transfer none): the default application for this process, or %NULL
+ * Returns: (nullable) (transfer none): the default application for this process, or %NULL
*
* Since: 2.32
**/
/**
* g_application_set_default:
- * @application: (allow-none): the application to set as default, or %NULL
+ * @application: (nullable): the application to set as default, or %NULL
*
* Sets or unsets the default application for the process, as returned
* by g_application_get_default().
* calling only the 'shutdown' function before doing so.
*
* The hold count is ignored.
+ * Take care if your code has called g_application_hold() on the application and
+ * is therefore still expecting it to exist.
+ * (Note that you may have called g_application_hold() indirectly, for example
+ * through gtk_application_add_window().)
*
* The result of calling g_application_run() again after it returns is
* unspecified.
application->priv->busy_count++;
if (!was_busy)
- g_application_impl_set_busy_state (application->priv->impl, TRUE);
+ {
+ g_application_impl_set_busy_state (application->priv->impl, TRUE);
+ g_object_notify (G_OBJECT (application), "is-busy");
+ }
}
/**
application->priv->busy_count--;
if (application->priv->busy_count == 0)
- g_application_impl_set_busy_state (application->priv->impl, FALSE);
+ {
+ g_application_impl_set_busy_state (application->priv->impl, FALSE);
+ g_object_notify (G_OBJECT (application), "is-busy");
+ }
+}
+
+/**
+ * g_application_get_is_busy:
+ * @application: a #GApplication
+ *
+ * Gets the application's current busy state, as set through
+ * g_application_mark_busy() or g_application_bind_busy_property().
+ *
+ * Returns: %TRUE if @application is currently marked as busy
+ *
+ * Since: 2.44
+ */
+gboolean
+g_application_get_is_busy (GApplication *application)
+{
+ g_return_val_if_fail (G_IS_APPLICATION (application), FALSE);
+
+ return application->priv->busy_count > 0;
}
/* Notifications {{{1 */
/**
* g_application_send_notification:
* @application: a #GApplication
- * @id: (allow-none): id of the notification, or %NULL
+ * @id: (nullable): id of the notification, or %NULL
* @notification: the #GNotification to send
*
* Sends a notification on behalf of @application to the desktop shell.
g_return_if_fail (G_IS_APPLICATION (application));
g_return_if_fail (id != NULL);
- if (application->priv->notifications)
- g_notification_backend_withdraw_notification (application->priv->notifications, id);
+ if (application->priv->notifications == NULL)
+ application->priv->notifications = g_notification_backend_new_default (application);
+
+ g_notification_backend_withdraw_notification (application->priv->notifications, id);
+}
+
+/* Busy binding {{{1 */
+
+typedef struct
+{
+ GApplication *app;
+ gboolean is_busy;
+} GApplicationBusyBinding;
+
+static void
+g_application_busy_binding_destroy (gpointer data,
+ GClosure *closure)
+{
+ GApplicationBusyBinding *binding = data;
+
+ if (binding->is_busy)
+ g_application_unmark_busy (binding->app);
+
+ g_object_unref (binding->app);
+ g_slice_free (GApplicationBusyBinding, binding);
+}
+
+static void
+g_application_notify_busy_binding (GObject *object,
+ GParamSpec *pspec,
+ gpointer user_data)
+{
+ GApplicationBusyBinding *binding = user_data;
+ gboolean is_busy;
+
+ g_object_get (object, pspec->name, &is_busy, NULL);
+
+ if (is_busy && !binding->is_busy)
+ g_application_mark_busy (binding->app);
+ else if (!is_busy && binding->is_busy)
+ g_application_unmark_busy (binding->app);
+
+ binding->is_busy = is_busy;
+}
+
+/**
+ * g_application_bind_busy_property:
+ * @application: a #GApplication
+ * @object: (type GObject.Object): a #GObject
+ * @property: the name of a boolean property of @object
+ *
+ * Marks @application as busy (see g_application_mark_busy()) while
+ * @property on @object is %TRUE.
+ *
+ * The binding holds a reference to @application while it is active, but
+ * not to @object. Instead, the binding is destroyed when @object is
+ * finalized.
+ *
+ * Since: 2.44
+ */
+void
+g_application_bind_busy_property (GApplication *application,
+ gpointer object,
+ const gchar *property)
+{
+ guint notify_id;
+ GQuark property_quark;
+ GParamSpec *pspec;
+ GApplicationBusyBinding *binding;
+ GClosure *closure;
+
+ g_return_if_fail (G_IS_APPLICATION (application));
+ g_return_if_fail (G_IS_OBJECT (object));
+ g_return_if_fail (property != NULL);
+
+ notify_id = g_signal_lookup ("notify", G_TYPE_OBJECT);
+ property_quark = g_quark_from_string (property);
+ pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (object), property);
+
+ g_return_if_fail (pspec != NULL && pspec->value_type == G_TYPE_BOOLEAN);
+
+ if (g_signal_handler_find (object, G_SIGNAL_MATCH_ID | G_SIGNAL_MATCH_DETAIL | G_SIGNAL_MATCH_FUNC,
+ notify_id, property_quark, NULL, g_application_notify_busy_binding, NULL) > 0)
+ {
+ g_critical ("%s: '%s' is already bound to the busy state of the application", G_STRFUNC, property);
+ return;
+ }
+
+ binding = g_slice_new (GApplicationBusyBinding);
+ binding->app = g_object_ref (application);
+ binding->is_busy = FALSE;
+
+ closure = g_cclosure_new (G_CALLBACK (g_application_notify_busy_binding), binding,
+ g_application_busy_binding_destroy);
+ g_signal_connect_closure_by_id (object, notify_id, property_quark, closure, FALSE);
+
+ /* fetch the initial value */
+ g_application_notify_busy_binding (object, pspec, binding);
+}
+
+/**
+ * g_application_unbind_busy_property:
+ * @application: a #GApplication
+ * @object: (type GObject.Object): a #GObject
+ * @property: the name of a boolean property of @object
+ *
+ * Destroys a binding between @property and the busy state of
+ * @application that was previously created with
+ * g_application_bind_busy_property().
+ *
+ * Since: 2.44
+ */
+void
+g_application_unbind_busy_property (GApplication *application,
+ gpointer object,
+ const gchar *property)
+{
+ guint notify_id;
+ GQuark property_quark;
+ gulong handler_id;
+
+ g_return_if_fail (G_IS_APPLICATION (application));
+ g_return_if_fail (G_IS_OBJECT (object));
+ g_return_if_fail (property != NULL);
+
+ notify_id = g_signal_lookup ("notify", G_TYPE_OBJECT);
+ property_quark = g_quark_from_string (property);
+
+ handler_id = g_signal_handler_find (object, G_SIGNAL_MATCH_ID | G_SIGNAL_MATCH_DETAIL | G_SIGNAL_MATCH_FUNC,
+ notify_id, property_quark, NULL, g_application_notify_busy_binding, NULL);
+ if (handler_id == 0)
+ {
+ g_critical ("%s: '%s' is not bound to the busy state of the application", G_STRFUNC, property);
+ return;
+ }
+
+ g_signal_handler_disconnect (object, handler_id);
}
/* Epilogue {{{1 */