* vfunc, to parse them in either the primary instance or the local instance,
* respectively.
*
- * <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-open.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
- *
- * <example id="gapplication-example-actions"><title>A GApplication with actions</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-actions.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
- *
- * <example id="gapplication-example-dbushooks"><title>Using extra D-Bus hooks with a GApplication</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-dbushooks.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
+ * For an example of opening files with a GApplication, see
+ * [gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c).
+ *
+ * For an example of using actions with GApplication, see
+ * [gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c).
+ *
+ * For an example of using extra D-Bus hooks with GApplication, see
+ * [gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c).
*/
/**
{
GApplicationFlags flags;
gchar *id;
+ gchar *resource_path;
GActionGroup *actions;
GMenuModel *app_menu;
GSList *option_groups;
GHashTable *packed_options;
gboolean options_parsed;
+
+ /* Allocated option strings, from g_application_add_main_option() */
+ GSList *option_strings;
};
enum
PROP_NONE,
PROP_APPLICATION_ID,
PROP_FLAGS,
+ PROP_RESOURCE_BASE_PATH,
PROP_IS_REGISTERED,
PROP_IS_REMOTE,
PROP_INACTIVITY_TIMEOUT,
context = g_option_context_new (NULL);
+ /* 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.
/**
* g_application_add_main_option_entries:
* @application: a #GApplication
- * @entries: a %NULL-terminated list of #GOptionEntrys
+ * @entries: (array zero-terminated=1) (element-type GOptionEntry) a
+ * %NULL-terminated list of #GOptionEntrys
*
* Adds main option entries to be handled by @application.
*
for (i = 0; entries[i].long_name; i++)
{
- GOptionEntry my_entries[2] = { entries[i], { NULL } };
+ GOptionEntry my_entries[2] = { { NULL }, { NULL } };
+ my_entries[0] = entries[i];
if (!my_entries[0].arg_data)
add_packed_option (application, &my_entries[0]);
}
/**
+ * g_application_add_main_option:
+ * @application: the #GApplication
+ * @long_name: the long name of an option used to specify it in a commandline
+ * @short_name: the short name of an option
+ * @flags: flags from #GOptionFlags
+ * @arg: the type of the option, as a #GOptionArg
+ * @description: the description for the option in `--help` output
+ * @arg_description: (nullable): the placeholder to use for the extra argument
+ * parsed by the option in `--help` output
+ *
+ * Add an option to be handled by @application.
+ *
+ * Calling this function is the equivalent of calling
+ * g_application_add_main_option_entries() with a single #GOptionEntry
+ * that has its arg_data member set to %NULL.
+ *
+ * The parsed arguments will be packed into a #GVariantDict which
+ * is passed to #GApplication::handle-local-options. If
+ * %G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also
+ * be sent to the primary instance. See
+ * g_application_add_main_option_entries() for more details.
+ *
+ * See #GOptionEntry for more documentation of the arguments.
+ *
+ * Since: 2.42
+ **/
+void
+g_application_add_main_option (GApplication *application,
+ const char *long_name,
+ char short_name,
+ GOptionFlags flags,
+ GOptionArg arg,
+ const char *description,
+ const char *arg_description)
+{
+ gchar *dup_string;
+ GOptionEntry my_entry[2] = {
+ { NULL, short_name, flags, arg, NULL, NULL, NULL },
+ { NULL }
+ };
+
+ g_return_if_fail (G_IS_APPLICATION (application));
+ g_return_if_fail (long_name != NULL);
+ g_return_if_fail (description != NULL);
+
+ my_entry[0].long_name = dup_string = g_strdup (long_name);
+ application->priv->option_strings = g_slist_prepend (application->priv->option_strings, dup_string);
+
+ my_entry[0].description = dup_string = g_strdup (description);
+ application->priv->option_strings = g_slist_prepend (application->priv->option_strings, dup_string);
+
+ my_entry[0].arg_description = dup_string = g_strdup (arg_description);
+ application->priv->option_strings = g_slist_prepend (application->priv->option_strings, dup_string);
+
+ g_application_add_main_option_entries (application, my_entry);
+}
+
+/**
* g_application_add_option_group:
* @application: the #GApplication
* @group: a #GOptionGroup
*
* This means that the options from #GOptionGroup are only really usable
* in the case that the instance of the application being run is the
- * first instance. Passing options like <literal>--display=</literal>
- * or <literal>--gdk-debug=</literal> on future runs will have no effect
- * on the existing primary instance.
+ * first instance. Passing options like `--display=` or `--gdk-debug=`
+ * on future runs will have no effect on the existing primary instance.
*
* Calling this function will cause the options in the supplied option
* group to be parsed, but it does not cause you to be "opted in" to the
g_application_set_flags (application, g_value_get_flags (value));
break;
+ case PROP_RESOURCE_BASE_PATH:
+ g_application_set_resource_base_path (application, g_value_get_string (value));
+ break;
+
case PROP_INACTIVITY_TIMEOUT:
g_application_set_inactivity_timeout (application,
g_value_get_uint (value));
g_application_get_flags (application));
break;
+ case PROP_RESOURCE_BASE_PATH:
+ g_value_set_string (value, g_application_get_resource_base_path (application));
+ break;
+
case PROP_IS_REGISTERED:
g_value_set_boolean (value,
g_application_get_is_registered (application));
if (g_application_get_default () == NULL)
g_application_set_default (application);
+
+ /* People should not set properties from _init... */
+ g_assert (application->priv->resource_path == NULL);
+
+ if (application->priv->id != NULL)
+ {
+ gint i;
+
+ application->priv->resource_path = g_strconcat ("/", application->priv->id, NULL);
+
+ for (i = 1; application->priv->resource_path[i]; i++)
+ if (application->priv->resource_path[i] == '.')
+ application->priv->resource_path[i] = '/';
+ }
}
static void
if (application->priv->main_options)
g_option_group_free (application->priv->main_options);
if (application->priv->packed_options)
- g_hash_table_unref (application->priv->packed_options);
-
+ {
+ g_slist_free_full (application->priv->option_strings, g_free);
+ g_hash_table_unref (application->priv->packed_options);
+ }
if (application->priv->impl)
g_application_impl_destroy (application->priv->impl);
g_free (application->priv->id);
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);
}
G_TYPE_APPLICATION_FLAGS, G_APPLICATION_FLAGS_NONE,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+ g_object_class_install_property (object_class, PROP_RESOURCE_BASE_PATH,
+ g_param_spec_string ("resource-base-path",
+ P_("Resource base path"),
+ P_("The base resource path for the application"),
+ NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
g_object_class_install_property (object_class, PROP_IS_REGISTERED,
g_param_spec_boolean ("is-registered",
P_("Is registered"),
* 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
* the application first. You should probably not call
* g_application_activate() for yourself, however: just return -1 and
* allow the default handler to do it for you. This will ensure that
- * the <literal>--gapplication-service</literal> switch works properly
- * (ie: no activation in that case).
+ * the `--gapplication-service` switch works properly (i.e. no activation
+ * in that case).
*
* Note that this signal is emitted from the default implementation of
* local_command_line(). If you override that function and don't
* 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_application_get_resource_base_path:
+ * @application: a #GApplication
+ *
+ * Gets the resource base path of @application.
+ *
+ * See g_application_set_resource_base_path() for more information.
+ *
+ * Returns: (nullable): the base resource path, if one is set
+ *
+ * Since: 2.42
+ */
+const gchar *
+g_application_get_resource_base_path (GApplication *application)
+{
+ g_return_val_if_fail (G_IS_APPLICATION (application), NULL);
+
+ return application->priv->resource_path;
+}
+
+/**
+ * g_application_set_resource_base_path:
+ * @application: a #GApplication
+ * @resource_path: (nullable): the resource path to use
+ *
+ * Sets (or unsets) the base resource path of @application.
+ *
+ * The path is used to automatically load various [application
+ * resources][gresource] such as menu layouts and action descriptions.
+ * The various types of resources will be found at fixed names relative
+ * to the given base path.
+ *
+ * By default, the resource base path is determined from the application
+ * ID by prefixing '/' and replacing each '.' with '/'. This is done at
+ * the time that the #GApplication object is constructed. Changes to
+ * the application ID after that point will not have an impact on the
+ * resource base path.
+ *
+ * As an example, if the application has an ID of "org.example.app" then
+ * the default resource base path will be "/org/example/app". If this
+ * is a #GtkApplication (and you have not manually changed the path)
+ * then Gtk will then search for the menus of the application at
+ * "/org/example/app/gtk/menus.ui".
+ *
+ * See #GResource for more information about adding resources to your
+ * application.
+ *
+ * You can disable automatic resource loading functionality by setting
+ * the path to %NULL.
+ *
+ * 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.
+ *
+ * Since: 2.42
+ */
+void
+g_application_set_resource_base_path (GApplication *application,
+ 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, "/"));
+
+ if (g_strcmp0 (application->priv->resource_path, resource_path) != 0)
+ {
+ g_free (application->priv->resource_path);
+
+ application->priv->resource_path = g_strdup (resource_path);
+
+ g_object_notify (G_OBJECT (application), "resource-base-path");
+ }
+}
+
+/**
* g_application_get_inactivity_timeout:
* @application: a #GApplication
*
return g_application_impl_get_dbus_object_path (application->priv->impl);
}
+
/* Register {{{1 */
/**
* g_application_register:
g_application_release (GApplication *application)
{
g_return_if_fail (G_IS_APPLICATION (application));
+ g_return_if_fail (application->priv->use_count > 0);
application->priv->use_count--;
* application can inspect the values of its #GOptionEntrys.
*
* #GApplication::handle-local-options is a good place to handle options
- * such as <literal>--version</literal>, where an immediate reply from
- * the local process is desired (instead of communicating with an
- * already-running instance). A #GApplication::handle-local-options
- * handler can stop further processing by returning a non-negative
- * value, which then becomes the exit status of the process.
+ * such as `--version`, where an immediate reply from the local process is
+ * desired (instead of communicating with an already-running instance).
+ * A #GApplication::handle-local-options handler can stop further processing
+ * by returning a non-negative value, which then becomes the exit status of
+ * the process.
*
* What happens next depends on the flags: if
* %G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining