2 * Copyright © 2010 Codethink Limited
4 * This program is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published
6 * by the Free Software Foundation; either version 2 of the licence or (at
7 * your option) any later version.
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.
14 * You should have received a copy of the GNU Lesser General
15 * Public 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.
19 * Authors: Ryan Lortie <desrt@desrt.ca>
25 #include "gapplication.h"
27 #include "gapplicationcommandline.h"
28 #include "gapplicationimpl.h"
29 #include "gactiongroup.h"
31 #include "gioenumtypes.h"
32 #include "gio-marshal.h"
41 * SECTION:gapplication
42 * @title: GApplication
43 * @short_description: Core application class
45 * A #GApplication is the foundation of an application, unique for a
46 * given application identifier. The GApplication class wraps some
47 * low-level platform-specific services and is intended to act as the
48 * foundation for higher-level application classes such as
49 * #GtkApplication or #MxApplication. In general, you should not use
50 * this class outside of a higher level framework.
52 * One of the core features that GApplication provides is process
53 * uniqueness, in the context of a "session". The session concept is
54 * platform-dependent, but corresponds roughly to a graphical desktop
55 * login. When your application is launched again, its arguments
56 * are passed through platform communication to the already running
57 * program. The already running instance of the program is called the
58 * <firstterm>primary instance</firstterm>.
60 * Before using GApplication, you must choose an "application identifier".
61 * The expected form of an application identifier is very close to that of
62 * of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>.
63 * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
64 * For details on valid application identifiers, see
65 * g_application_id_is_valid().
67 * The application identifier is claimed by the application as a
68 * well-known bus name on the user's session bus. This means that the
69 * uniqueness of your application is scoped to the current session. It
70 * also means that your application may provide additional services
71 * (through registration of other object paths) at that bus name.
73 * The registration of these object paths should be done with the shared
74 * GDBus session bus. Note that due to the internal architecture of
75 * GDBus, method calls can be dispatched at any time (even if a main
76 * loop is not running). For this reason, you must ensure that any
77 * object paths that you wish to register are registered before
78 * #GApplication attempts to acquire the bus name of your application
79 * (which happens in g_application_register()). Unfortunately, this
80 * means that you can not use g_application_get_is_remote() to decide if
81 * you want to register object paths.
83 * GApplication provides convenient life cycle management by maintaining
84 * a <firstterm>use count</firstterm> for the primary application instance.
85 * The use count can be changed using g_application_hold() and
86 * g_application_release(). If it drops to zero, the application exits.
88 * GApplication also implements the #GActionGroup interface and lets you
89 * easily export actions by adding them with g_application_set_action_group().
90 * When invoking an action by calling g_action_group_activate_action() on
91 * the application, it is always invoked in the primary instance.
93 * There is a number of different entry points into a #GApplication:
95 * <listitem>via 'Activate' (i.e. just starting the application)</listitem>
96 * <listitem>via 'Open' (i.e. opening some files)</listitem>
97 * <listitem>via activating an action</listitem>
99 * The #GApplication::startup signal lets you handle the application
100 * initialization for all of these in a single place.
102 * <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
104 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-open.c">
105 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
110 * <example id="gapplication-example-actions"><title>A GApplication with actions</title>
112 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-actions.c">
113 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
119 struct _GApplicationPrivate
121 GApplicationFlags flags
;
124 GActionGroup
*actions
;
127 guint inactivity_timeout_id
;
128 guint inactivity_timeout
;
131 guint is_registered
: 1;
134 GHashTable
*remote_actions
; /* string -> RemoteActionInfo */
135 GApplicationImpl
*impl
;
145 PROP_INACTIVITY_TIMEOUT
,
159 static guint g_application_signals
[NR_SIGNALS
];
161 static void g_application_action_group_iface_init (GActionGroupInterface
*);
162 G_DEFINE_TYPE_WITH_CODE (GApplication
, g_application
, G_TYPE_OBJECT
,
163 G_IMPLEMENT_INTERFACE (G_TYPE_ACTION_GROUP
,
164 g_application_action_group_iface_init
))
166 /* vfunc defaults {{{1 */
168 g_application_real_before_emit (GApplication
*application
,
169 GVariant
*platform_data
)
174 g_application_real_after_emit (GApplication
*application
,
175 GVariant
*platform_data
)
180 g_application_real_startup (GApplication
*application
)
185 g_application_real_activate (GApplication
*application
)
187 if (!g_signal_has_handler_pending (application
,
188 g_application_signals
[SIGNAL_ACTIVATE
],
190 G_APPLICATION_GET_CLASS (application
)->activate
== g_application_real_activate
)
192 static gboolean warned
;
197 g_warning ("Your application does not implement "
198 "g_application_activate() and has no handlers connected "
199 "to the 'activate' signal. It should do one of these.");
205 g_application_real_open (GApplication
*application
,
210 if (!g_signal_has_handler_pending (application
,
211 g_application_signals
[SIGNAL_OPEN
],
213 G_APPLICATION_GET_CLASS (application
)->open
== g_application_real_open
)
215 static gboolean warned
;
220 g_warning ("Your application claims to support opening files "
221 "but does not implement g_application_open() and has no "
222 "handlers connected to the 'open' signal.");
228 g_application_real_command_line (GApplication
*application
,
229 GApplicationCommandLine
*cmdline
)
231 static gboolean warned
;
236 g_warning ("Your application claims to support custom command line "
237 "handling but does not implement g_application_command_line() "
238 "and has no handlers connected to the 'command-line' signal.");
246 g_application_real_local_command_line (GApplication
*application
,
250 if (application
->priv
->flags
& G_APPLICATION_HANDLES_COMMAND_LINE
)
255 GError
*error
= NULL
;
258 if (!g_application_register (application
, NULL
, &error
))
260 g_critical ("%s", error
->message
);
261 g_error_free (error
);
266 n_args
= g_strv_length (*arguments
);
268 if (application
->priv
->flags
& G_APPLICATION_IS_SERVICE
)
270 if ((*exit_status
= n_args
> 1))
272 g_printerr ("GApplication service mode takes no arguments.\n");
273 application
->priv
->flags
&= ~G_APPLICATION_IS_SERVICE
;
281 g_application_activate (application
);
287 if (~application
->priv
->flags
& G_APPLICATION_HANDLES_OPEN
)
289 g_critical ("This application can not open files.");
298 n_files
= n_args
- 1;
299 files
= g_new (GFile
*, n_files
);
301 for (i
= 0; i
< n_files
; i
++)
302 files
[i
] = g_file_new_for_commandline_arg ((*arguments
)[i
+ 1]);
304 g_application_open (application
, files
, n_files
, "");
306 for (i
= 0; i
< n_files
; i
++)
307 g_object_unref (files
[i
]);
319 g_application_real_add_platform_data (GApplication
*application
,
320 GVariantBuilder
*builder
)
325 g_application_real_quit_mainloop (GApplication
*application
)
327 if (application
->priv
->mainloop
!= NULL
)
328 g_main_loop_quit (application
->priv
->mainloop
);
332 g_application_real_run_mainloop (GApplication
*application
)
334 if (application
->priv
->mainloop
== NULL
)
335 application
->priv
->mainloop
= g_main_loop_new (NULL
, FALSE
);
337 g_main_loop_run (application
->priv
->mainloop
);
340 /* GObject implementation stuff {{{1 */
342 g_application_set_property (GObject
*object
,
347 GApplication
*application
= G_APPLICATION (object
);
351 case PROP_APPLICATION_ID
:
352 g_application_set_application_id (application
,
353 g_value_get_string (value
));
357 g_application_set_flags (application
, g_value_get_flags (value
));
360 case PROP_INACTIVITY_TIMEOUT
:
361 g_application_set_inactivity_timeout (application
,
362 g_value_get_uint (value
));
365 case PROP_ACTION_GROUP
:
366 g_application_set_action_group (application
,
367 g_value_get_object (value
));
371 g_assert_not_reached ();
376 * g_application_set_action_group:
377 * @application: a #GApplication
378 * @action_group: (allow-none): a #GActionGroup, or %NULL
380 * Sets or unsets the group of actions associated with the application.
382 * These actions are the actions that can be remotely invoked.
384 * It is an error to call this function after the application has been
390 g_application_set_action_group (GApplication
*application
,
391 GActionGroup
*action_group
)
393 g_return_if_fail (G_IS_APPLICATION (application
));
394 g_return_if_fail (!application
->priv
->is_registered
);
396 if (application
->priv
->actions
!= NULL
)
397 g_object_unref (application
->priv
->actions
);
399 application
->priv
->actions
= action_group
;
401 if (application
->priv
->actions
!= NULL
)
402 g_object_ref (application
->priv
->actions
);
406 g_application_get_property (GObject
*object
,
411 GApplication
*application
= G_APPLICATION (object
);
415 case PROP_APPLICATION_ID
:
416 g_value_set_string (value
,
417 g_application_get_application_id (application
));
421 g_value_set_flags (value
,
422 g_application_get_flags (application
));
425 case PROP_IS_REGISTERED
:
426 g_value_set_boolean (value
,
427 g_application_get_is_registered (application
));
431 g_value_set_boolean (value
,
432 g_application_get_is_remote (application
));
435 case PROP_INACTIVITY_TIMEOUT
:
436 g_value_set_uint (value
,
437 g_application_get_inactivity_timeout (application
));
441 g_assert_not_reached ();
446 g_application_constructed (GObject
*object
)
448 GApplication
*application
= G_APPLICATION (object
);
450 g_assert (application
->priv
->id
!= NULL
);
454 g_application_finalize (GObject
*object
)
456 GApplication
*application
= G_APPLICATION (object
);
458 if (application
->priv
->impl
)
459 g_application_impl_destroy (application
->priv
->impl
);
460 g_free (application
->priv
->id
);
462 if (application
->priv
->mainloop
)
463 g_main_loop_unref (application
->priv
->mainloop
);
465 G_OBJECT_CLASS (g_application_parent_class
)
470 g_application_init (GApplication
*application
)
472 application
->priv
= G_TYPE_INSTANCE_GET_PRIVATE (application
,
474 GApplicationPrivate
);
478 g_application_class_init (GApplicationClass
*class)
480 GObjectClass
*object_class
= G_OBJECT_CLASS (class);
482 object_class
->constructed
= g_application_constructed
;
483 object_class
->finalize
= g_application_finalize
;
484 object_class
->get_property
= g_application_get_property
;
485 object_class
->set_property
= g_application_set_property
;
487 class->before_emit
= g_application_real_before_emit
;
488 class->after_emit
= g_application_real_after_emit
;
489 class->startup
= g_application_real_startup
;
490 class->activate
= g_application_real_activate
;
491 class->open
= g_application_real_open
;
492 class->command_line
= g_application_real_command_line
;
493 class->local_command_line
= g_application_real_local_command_line
;
494 class->add_platform_data
= g_application_real_add_platform_data
;
495 class->quit_mainloop
= g_application_real_quit_mainloop
;
496 class->run_mainloop
= g_application_real_run_mainloop
;
498 g_object_class_install_property (object_class
, PROP_APPLICATION_ID
,
499 g_param_spec_string ("application-id",
500 P_("Application identifier"),
501 P_("The unique identifier for the application"),
502 NULL
, G_PARAM_READWRITE
| G_PARAM_CONSTRUCT
|
503 G_PARAM_STATIC_STRINGS
));
505 g_object_class_install_property (object_class
, PROP_FLAGS
,
506 g_param_spec_flags ("flags",
507 P_("Application flags"),
508 P_("Flags specifying the behaviour of the application"),
509 G_TYPE_APPLICATION_FLAGS
, G_APPLICATION_FLAGS_NONE
,
510 G_PARAM_READWRITE
| G_PARAM_STATIC_STRINGS
));
512 g_object_class_install_property (object_class
, PROP_IS_REGISTERED
,
513 g_param_spec_boolean ("is-registered",
515 P_("If g_application_register() has been called"),
516 FALSE
, G_PARAM_READABLE
| G_PARAM_STATIC_STRINGS
));
518 g_object_class_install_property (object_class
, PROP_IS_REMOTE
,
519 g_param_spec_boolean ("is-remote",
521 P_("If this application instance is remote"),
522 FALSE
, G_PARAM_READABLE
| G_PARAM_STATIC_STRINGS
));
524 g_object_class_install_property (object_class
, PROP_INACTIVITY_TIMEOUT
,
525 g_param_spec_uint ("inactivity-timeout",
526 P_("Inactivity timeout"),
527 P_("Iime (ms) to stay alive after becoming idle"),
529 G_PARAM_READWRITE
| G_PARAM_STATIC_STRINGS
));
531 g_object_class_install_property (object_class
, PROP_ACTION_GROUP
,
532 g_param_spec_object ("action-group",
534 P_("The group of actions that the application exports"),
536 G_PARAM_WRITABLE
| G_PARAM_STATIC_STRINGS
));
539 * GApplication::startup:
540 * @application: the application
542 * The ::startup signal is emitted on the primary instance immediately
543 * after registration. See g_activation_register().
545 g_application_signals
[SIGNAL_STARTUP
] =
546 g_signal_new ("startup", G_TYPE_APPLICATION
, G_SIGNAL_RUN_LAST
,
547 G_STRUCT_OFFSET (GApplicationClass
, startup
),
548 NULL
, NULL
, g_cclosure_marshal_VOID__VOID
, G_TYPE_NONE
, 0);
551 * GApplication::activate:
552 * @application: the application
554 * The ::activate signal is emitted on the primary instance when an
555 * activation occurs. See g_application_activate().
557 g_application_signals
[SIGNAL_ACTIVATE
] =
558 g_signal_new ("activate", G_TYPE_APPLICATION
, G_SIGNAL_RUN_LAST
,
559 G_STRUCT_OFFSET (GApplicationClass
, activate
),
560 NULL
, NULL
, g_cclosure_marshal_VOID__VOID
, G_TYPE_NONE
, 0);
564 * GApplication::open:
565 * @application: the application
566 * @files: (array length=n_files) (element-type GFile): an array of #GFiles
567 * @n_files: the length of @files
568 * @hint: a hint provided by the calling instance
570 * The ::open signal is emitted on the primary instance when there are
571 * files to open. See g_application_open() for more information.
573 g_application_signals
[SIGNAL_OPEN
] =
574 g_signal_new ("open", G_TYPE_APPLICATION
, G_SIGNAL_RUN_LAST
,
575 G_STRUCT_OFFSET (GApplicationClass
, open
),
576 NULL
, NULL
, _gio_marshal_VOID__POINTER_INT_STRING
,
577 G_TYPE_NONE
, 3, G_TYPE_POINTER
, G_TYPE_INT
, G_TYPE_STRING
);
580 * GApplication::command-line:
581 * @application: the application
582 * @command_line: a #GApplicationCommandLine representing the
585 * The ::command-line signal is emitted on the primary instance when
586 * a commandline is not handled locally. See g_application_run() for
589 g_application_signals
[SIGNAL_COMMAND_LINE
] =
590 g_signal_new ("command-line", G_TYPE_APPLICATION
, G_SIGNAL_RUN_LAST
,
591 G_STRUCT_OFFSET (GApplicationClass
, command_line
),
592 g_signal_accumulator_first_wins
, NULL
,
593 _gio_marshal_INT__OBJECT
,
594 G_TYPE_INT
, 1, G_TYPE_APPLICATION_COMMAND_LINE
);
596 g_type_class_add_private (class, sizeof (GApplicationPrivate
));
600 get_platform_data (GApplication
*application
)
602 GVariantBuilder
*builder
;
605 builder
= g_variant_builder_new (G_VARIANT_TYPE ("a{sv}"));
608 gchar
*cwd
= g_get_current_dir ();
609 g_variant_builder_add (builder
, "{sv}", "cwd",
610 g_variant_new_bytestring (cwd
));
614 if (application
->priv
->flags
& G_APPLICATION_SEND_ENVIRONMENT
)
619 envp
= g_get_environ ();
620 array
= g_variant_new_bytestring_array ((const gchar
**) envp
, -1);
623 g_variant_builder_add (builder
, "{sv}", "environ", array
);
626 G_APPLICATION_GET_CLASS (application
)->
627 add_platform_data (application
, builder
);
629 result
= g_variant_builder_end (builder
);
630 g_variant_builder_unref (builder
);
635 /* Application ID validity {{{1 */
638 * g_application_id_is_valid:
639 * @application_id: a potential application identifier
640 * @returns: %TRUE if @application_id is valid
642 * Checks if @application_id is a valid application identifier.
644 * A valid ID is required for calls to g_application_new() and
645 * g_application_set_application_id().
647 * For convenience, the restrictions on application identifiers are
650 * <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit.</listitem>
651 * <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least two elements).</listitem>
652 * <listitem>Application identifiers must not begin with a '.' (period) character.</listitem>
653 * <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
654 * <listitem>Application identifiers must not exceed 255 characters.</listitem>
658 g_application_id_is_valid (const gchar
*application_id
)
662 if (strlen (application_id
) > 255)
665 if (!g_ascii_isalpha (*application_id
))
670 for (; *application_id
; application_id
++)
672 if (g_ascii_isalnum (*application_id
) ||
673 (*application_id
== '-') ||
674 (*application_id
== '_'))
676 else if (allow_dot
&& *application_id
== '.')
685 /* Public Constructor {{{1 */
688 * @application_id: the application id
689 * @flags: the application flags
690 * @returns: a new #GApplication instance
692 * Creates a new #GApplication instance.
694 * This function calls g_type_init() for you.
696 * The application id must be valid. See g_application_id_is_valid().
699 g_application_new (const gchar
*application_id
,
700 GApplicationFlags flags
)
702 g_return_val_if_fail (g_application_id_is_valid (application_id
), NULL
);
706 return g_object_new (G_TYPE_APPLICATION
,
707 "application-id", application_id
,
712 /* Simple get/set: application id, flags, inactivity timeout {{{1 */
714 * g_application_get_application_id:
715 * @application: a #GApplication
716 * @returns: the identifier for @application, owned by @application
718 * Gets the unique identifier for @application.
723 g_application_get_application_id (GApplication
*application
)
725 g_return_val_if_fail (G_IS_APPLICATION (application
), NULL
);
727 return application
->priv
->id
;
731 * g_application_set_application_id:
732 * @application: a #GApplication
733 * @application_id: the identifier for @application
735 * Sets the unique identifier for @application.
737 * The application id can only be modified if @application has not yet
740 * The application id must be valid. See g_application_id_is_valid().
745 g_application_set_application_id (GApplication
*application
,
746 const gchar
*application_id
)
748 g_return_if_fail (G_IS_APPLICATION (application
));
750 if (g_strcmp0 (application
->priv
->id
, application_id
) != 0)
752 g_return_if_fail (g_application_id_is_valid (application_id
));
753 g_return_if_fail (!application
->priv
->is_registered
);
755 g_free (application
->priv
->id
);
756 application
->priv
->id
= g_strdup (application_id
);
758 g_object_notify (G_OBJECT (application
), "application-id");
763 * g_application_get_flags:
764 * @application: a #GApplication
765 * @returns: the flags for @application
767 * Gets the flags for @application.
769 * See #GApplicationFlags.
774 g_application_get_flags (GApplication
*application
)
776 g_return_val_if_fail (G_IS_APPLICATION (application
), 0);
778 return application
->priv
->flags
;
782 * g_application_set_flags:
783 * @application: a #GApplication
784 * @flags: the flags for @application
786 * Sets the flags for @application.
788 * The flags can only be modified if @application has not yet been
791 * See #GApplicationFlags.
796 g_application_set_flags (GApplication
*application
,
797 GApplicationFlags flags
)
799 g_return_if_fail (G_IS_APPLICATION (application
));
801 if (application
->priv
->flags
!= flags
)
803 g_return_if_fail (!application
->priv
->is_registered
);
805 application
->priv
->flags
= flags
;
807 g_object_notify (G_OBJECT (application
), "flags");
812 * g_application_get_inactivity_timeout:
813 * @application: a #GApplication
815 * Gets the current inactivity timeout for the application.
817 * This is the amount of time (in milliseconds) after the last call to
818 * g_application_release() before the application stops running.
820 * Returns: the timeout, in milliseconds
825 g_application_get_inactivity_timeout (GApplication
*application
)
827 g_return_val_if_fail (G_IS_APPLICATION (application
), 0);
829 return application
->priv
->inactivity_timeout
;
833 * g_application_set_inactivity_timeout:
834 * @application: a #GApplication
835 * @inactivity_timeout: the timeout, in milliseconds
837 * Sets the current inactivity timeout for the application.
839 * This is the amount of time (in milliseconds) after the last call to
840 * g_application_release() before the application stops running.
842 * This call has no side effects of its own. The value set here is only
843 * used for next time g_application_release() drops the use count to
844 * zero. Any timeouts currently in progress are not impacted.
846 * Returns: the timeout, in milliseconds
851 g_application_set_inactivity_timeout (GApplication
*application
,
852 guint inactivity_timeout
)
854 g_return_if_fail (G_IS_APPLICATION (application
));
856 if (application
->priv
->inactivity_timeout
!= inactivity_timeout
)
858 application
->priv
->inactivity_timeout
= inactivity_timeout
;
860 g_object_notify (G_OBJECT (application
), "inactivity-timeout");
863 /* Read-only property getters (is registered, is remote) {{{1 */
865 * g_application_get_is_registered:
866 * @application: a #GApplication
867 * @returns: %TRUE if @application is registered
869 * Checks if @application is registered.
871 * An application is registered if g_application_register() has been
872 * successfully called.
877 g_application_get_is_registered (GApplication
*application
)
879 g_return_val_if_fail (G_IS_APPLICATION (application
), FALSE
);
881 return application
->priv
->is_registered
;
885 * g_application_get_is_remote:
886 * @application: a #GApplication
887 * @returns: %TRUE if @application is remote
889 * Checks if @application is remote.
891 * If @application is remote then it means that another instance of
892 * application already exists (the 'primary' instance). Calls to
893 * perform actions on @application will result in the actions being
894 * performed by the primary instance.
896 * The value of this property can not be accessed before
897 * g_application_register() has been called. See
898 * g_application_get_is_registered().
903 g_application_get_is_remote (GApplication
*application
)
905 g_return_val_if_fail (G_IS_APPLICATION (application
), FALSE
);
906 g_return_val_if_fail (application
->priv
->is_registered
, FALSE
);
908 return application
->priv
->is_remote
;
913 * g_application_register:
914 * @application: a #GApplication
915 * @cancellable: a #GCancellable, or %NULL
916 * @error: a pointer to a NULL #GError, or %NULL
917 * @returns: %TRUE if registration succeeded
919 * Attempts registration of the application.
921 * This is the point at which the application discovers if it is the
922 * primary instance or merely acting as a remote for an already-existing
923 * primary instance. This is implemented by attempting to acquire the
924 * application identifier as a uniue bus name on the session bus using
927 * Due to the internal architecture of GDBus, method calls can be
928 * dispatched at any time (even if a main loop is not running). For
929 * this reason, you must ensure that any object paths that you wish to
930 * register are registered before calling this function.
932 * If the application has already been registered then %TRUE is
933 * returned with no work performed.
935 * The #GApplication::startup signal is emitted if registration succeeds
936 * and @application is the primary instance.
938 * In the event of an error (such as @cancellable being cancelled, or a
939 * failure to connect to the session bus), %FALSE is returned and @error
940 * is set appropriately.
942 * Note: the return value of this function is not an indicator that this
943 * instance is or is not the primary instance of the application. See
944 * g_application_get_is_remote() for that.
949 g_application_register (GApplication
*application
,
950 GCancellable
*cancellable
,
953 g_return_val_if_fail (G_IS_APPLICATION (application
), FALSE
);
955 if (!application
->priv
->is_registered
)
957 application
->priv
->impl
=
958 g_application_impl_register (application
, application
->priv
->id
,
959 application
->priv
->flags
,
960 &application
->priv
->remote_actions
,
963 if (application
->priv
->impl
== NULL
)
966 application
->priv
->is_remote
= application
->priv
->remote_actions
!= NULL
;
967 application
->priv
->is_registered
= TRUE
;
969 g_object_notify (G_OBJECT (application
), "is-registered");
971 if (!application
->priv
->is_remote
)
972 g_signal_emit (application
, g_application_signals
[SIGNAL_STARTUP
], 0);
978 /* Hold/release {{{1 */
980 * g_application_hold:
981 * @application: a #GApplication
983 * Increases the use count of @application.
985 * Use this function to indicate that the application has a reason to
986 * continue to run. For example, g_application_hold() is called by GTK+
987 * when a toplevel window is on the screen.
989 * To cancel the hold, call g_application_release().
992 g_application_hold (GApplication
*application
)
994 if (application
->priv
->inactivity_timeout_id
)
996 g_source_remove (application
->priv
->inactivity_timeout_id
);
997 application
->priv
->inactivity_timeout_id
= 0;
1000 application
->priv
->use_count
++;
1004 inactivity_timeout_expired (gpointer data
)
1006 GApplication
*application
= G_APPLICATION (data
);
1008 G_APPLICATION_GET_CLASS (application
)
1009 ->quit_mainloop (application
);
1016 * g_application_release:
1017 * @application: a #GApplication
1019 * Decrease the use count of @application.
1021 * When the use count reaches zero, the application will stop running.
1023 * Never call this function except to cancel the effect of a previous
1024 * call to g_application_hold().
1027 g_application_release (GApplication
*application
)
1029 application
->priv
->use_count
--;
1031 if (application
->priv
->use_count
== 0)
1033 if (application
->priv
->inactivity_timeout
)
1034 application
->priv
->inactivity_timeout_id
=
1035 g_timeout_add (application
->priv
->inactivity_timeout
,
1036 inactivity_timeout_expired
, application
);
1039 G_APPLICATION_GET_CLASS (application
)
1040 ->quit_mainloop (application
);
1044 /* Activate, Open {{{1 */
1046 * g_application_activate:
1047 * @application: a #GApplication
1049 * Activates the application.
1051 * In essence, this results in the #GApplication::activate() signal being
1052 * emitted in the primary instance.
1054 * The application must be registered before calling this function.
1059 g_application_activate (GApplication
*application
)
1061 g_return_if_fail (G_IS_APPLICATION (application
));
1062 g_return_if_fail (application
->priv
->is_registered
);
1064 if (application
->priv
->is_remote
)
1065 g_application_impl_activate (application
->priv
->impl
,
1066 get_platform_data (application
));
1069 g_signal_emit (application
, g_application_signals
[SIGNAL_ACTIVATE
], 0);
1073 * g_application_open:
1074 * @application: a #GApplication
1075 * @files: (array length=n_files): an array of #GFiles to open
1076 * @n_files: the length of the @files array
1077 * @hint: a hint (or ""), but never %NULL
1079 * Opens the given files.
1081 * In essence, this results in the #GApplication::open signal being emitted
1082 * in the primary instance.
1084 * @n_files must be greater than zero.
1086 * @hint is simply passed through to the ::open signal. It is
1087 * intended to be used by applications that have multiple modes for
1088 * opening files (eg: "view" vs "edit", etc). Unless you have a need
1089 * for this functionality, you should use "".
1091 * The application must be registered before calling this function
1092 * and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
1097 g_application_open (GApplication
*application
,
1102 g_return_if_fail (G_IS_APPLICATION (application
));
1103 g_return_if_fail (application
->priv
->flags
&
1104 G_APPLICATION_HANDLES_OPEN
);
1105 g_return_if_fail (application
->priv
->is_registered
);
1107 if (application
->priv
->is_remote
)
1108 g_application_impl_open (application
->priv
->impl
,
1109 files
, n_files
, hint
,
1110 get_platform_data (application
));
1113 g_signal_emit (application
, g_application_signals
[SIGNAL_OPEN
],
1114 0, files
, n_files
, hint
);
1119 * g_application_run:
1120 * @application: a #GApplication
1121 * @argc: the argc from main()
1122 * @argv: (array length=argc): the argv from main()
1123 * @returns: the exit status
1125 * Runs the application.
1127 * This function is intended to be run from main() and its return value
1128 * is intended to be returned by main().
1130 * First, the local_command_line() virtual function is invoked. This
1131 * function always runs on the local instance. If that function returns
1132 * %FALSE then the application is registered and the #GApplication::command-line
1133 * signal is emitted in the primary instance (which may or may not be
1136 * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
1137 * flag set then the default implementation of local_command_line()
1138 * always returns %FALSE immediately, resulting in the commandline
1139 * always being handled in the primary instance.
1141 * Otherwise, the default implementation of local_command_line() tries
1142 * to do a couple of things that are probably reasonable for most
1143 * applications. First, g_application_register() is called to attempt
1144 * to register the application. If that works, then the command line
1145 * arguments are inspected. If no commandline arguments are given, then
1146 * g_application_activate() is called. If commandline arguments are
1147 * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they
1148 * are assumed to be filenames and g_application_open() is called.
1150 * If you are interested in doing more complicated local handling of the
1151 * commandline then you should implement your own #GApplication subclass
1152 * and override local_command_line(). See
1153 * <xref linkend="gapplication-example-cmdline2"/> for an example.
1155 * If, after the above is done, the use count of the application is zero
1156 * then the exit status is returned immediately. If the use count is
1157 * non-zero then the mainloop is run until the use count falls to zero,
1158 * at which point 0 is returned.
1160 * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at
1161 * use count of zero is delayed for a while (ie: the instance stays
1162 * around to provide its <emphasis>service</emphasis> to others).
1167 g_application_run (GApplication
*application
,
1175 g_return_val_if_fail (G_IS_APPLICATION (application
), 1);
1176 g_return_val_if_fail (argc
== 0 || argv
!= NULL
, 1);
1178 arguments
= g_new (gchar
*, argc
+ 1);
1179 for (i
= 0; i
< argc
; i
++)
1180 arguments
[i
] = g_strdup (argv
[i
]);
1181 arguments
[i
] = NULL
;
1183 if (g_get_prgname () == NULL
&& argc
> 0)
1187 prgname
= g_path_get_basename (argv
[0]);
1188 g_set_prgname (prgname
);
1192 if (!G_APPLICATION_GET_CLASS (application
)
1193 ->local_command_line (application
, &arguments
, &status
))
1195 GError
*error
= NULL
;
1197 if (!g_application_register (application
, NULL
, &error
))
1199 g_printerr ("%s", error
->message
);
1200 g_error_free (error
);
1204 if (application
->priv
->is_remote
)
1206 GVariant
*platform_data
;
1208 platform_data
= get_platform_data (application
);
1209 status
= g_application_impl_command_line (application
->priv
->impl
,
1210 arguments
, platform_data
);
1214 GApplicationCommandLine
*cmdline
;
1217 v
= g_variant_new_bytestring_array ((const gchar
**) arguments
, -1);
1218 cmdline
= g_object_new (G_TYPE_APPLICATION_COMMAND_LINE
,
1219 "arguments", v
, NULL
);
1220 g_signal_emit (application
,
1221 g_application_signals
[SIGNAL_COMMAND_LINE
],
1222 0, cmdline
, &status
);
1223 g_object_unref (cmdline
);
1227 g_strfreev (arguments
);
1229 if (application
->priv
->flags
& G_APPLICATION_IS_SERVICE
&&
1230 application
->priv
->is_registered
&&
1231 !application
->priv
->use_count
&&
1232 !application
->priv
->inactivity_timeout_id
)
1234 application
->priv
->inactivity_timeout_id
=
1235 g_timeout_add (10000, inactivity_timeout_expired
, application
);
1238 if (application
->priv
->use_count
||
1239 application
->priv
->inactivity_timeout_id
)
1241 G_APPLICATION_GET_CLASS (application
)
1242 ->run_mainloop (application
);
1246 if (application
->priv
->impl
)
1247 g_application_impl_flush (application
->priv
->impl
);
1253 g_application_has_action (GActionGroup
*action_group
,
1254 const gchar
*action_name
)
1256 GApplication
*application
= G_APPLICATION (action_group
);
1258 g_return_val_if_fail (application
->priv
->is_registered
, FALSE
);
1260 if (application
->priv
->remote_actions
!= NULL
)
1261 return g_hash_table_lookup (application
->priv
->remote_actions
,
1262 action_name
) != NULL
;
1264 return application
->priv
->actions
&&
1265 g_action_group_has_action (application
->priv
->actions
, action_name
);
1269 g_application_list_actions (GActionGroup
*action_group
)
1271 GApplication
*application
= G_APPLICATION (action_group
);
1273 g_return_val_if_fail (application
->priv
->is_registered
, NULL
);
1275 if (application
->priv
->remote_actions
!= NULL
)
1277 GHashTableIter iter
;
1282 n
= g_hash_table_size (application
->priv
->remote_actions
);
1283 keys
= g_new (gchar
*, n
+ 1);
1285 g_hash_table_iter_init (&iter
, application
->priv
->remote_actions
);
1286 while (g_hash_table_iter_next (&iter
, &key
, NULL
))
1287 keys
[i
++] = g_strdup (key
);
1288 g_assert_cmpint (i
, ==, n
);
1294 else if (application
->priv
->actions
!= NULL
)
1295 return g_action_group_list_actions (application
->priv
->actions
);
1298 /* empty string array */
1299 return g_new0 (gchar
*, 1);
1303 g_application_get_action_enabled (GActionGroup
*action_group
,
1304 const gchar
*action_name
)
1306 GApplication
*application
= G_APPLICATION (action_group
);
1308 g_return_val_if_fail (application
->priv
->actions
!= NULL
, FALSE
);
1309 g_return_val_if_fail (application
->priv
->is_registered
, FALSE
);
1311 if (application
->priv
->remote_actions
)
1313 RemoteActionInfo
*info
;
1315 info
= g_hash_table_lookup (application
->priv
->remote_actions
,
1318 return info
&& info
->enabled
;
1321 return g_action_group_get_action_enabled (application
->priv
->actions
,
1325 static const GVariantType
*
1326 g_application_get_action_parameter_type (GActionGroup
*action_group
,
1327 const gchar
*action_name
)
1329 GApplication
*application
= G_APPLICATION (action_group
);
1331 g_return_val_if_fail (application
->priv
->actions
!= NULL
, NULL
);
1332 g_return_val_if_fail (application
->priv
->is_registered
, NULL
);
1334 if (application
->priv
->remote_actions
)
1336 RemoteActionInfo
*info
;
1338 info
= g_hash_table_lookup (application
->priv
->remote_actions
,
1342 return info
->parameter_type
;
1347 return g_action_group_get_action_parameter_type (application
->priv
->actions
,
1351 static const GVariantType
*
1352 g_application_get_action_state_type (GActionGroup
*action_group
,
1353 const gchar
*action_name
)
1355 GApplication
*application
= G_APPLICATION (action_group
);
1357 g_return_val_if_fail (application
->priv
->actions
!= NULL
, NULL
);
1358 g_return_val_if_fail (application
->priv
->is_registered
, NULL
);
1360 if (application
->priv
->remote_actions
)
1362 RemoteActionInfo
*info
;
1364 info
= g_hash_table_lookup (application
->priv
->remote_actions
,
1367 if (info
&& info
->state
)
1368 return g_variant_get_type (info
->state
);
1373 return g_action_group_get_action_state_type (application
->priv
->actions
,
1378 g_application_get_action_state (GActionGroup
*action_group
,
1379 const gchar
*action_name
)
1381 GApplication
*application
= G_APPLICATION (action_group
);
1383 g_return_val_if_fail (application
->priv
->actions
!= NULL
, NULL
);
1384 g_return_val_if_fail (application
->priv
->is_registered
, NULL
);
1386 if (application
->priv
->remote_actions
)
1388 RemoteActionInfo
*info
;
1390 info
= g_hash_table_lookup (application
->priv
->remote_actions
,
1393 if (info
&& info
->state
)
1394 return g_variant_ref (info
->state
);
1399 return g_action_group_get_action_state (application
->priv
->actions
,
1404 g_application_change_action_state (GActionGroup
*action_group
,
1405 const gchar
*action_name
,
1408 GApplication
*application
= G_APPLICATION (action_group
);
1410 g_return_if_fail (application
->priv
->is_registered
);
1412 if (application
->priv
->is_remote
)
1413 g_application_impl_change_action_state (application
->priv
->impl
,
1415 get_platform_data (application
));
1418 g_action_group_change_action_state (application
->priv
->actions
,
1419 action_name
, value
);
1423 g_application_activate_action (GActionGroup
*action_group
,
1424 const gchar
*action_name
,
1425 GVariant
*parameter
)
1427 GApplication
*application
= G_APPLICATION (action_group
);
1429 g_return_if_fail (application
->priv
->is_registered
);
1431 if (application
->priv
->is_remote
)
1432 g_application_impl_activate_action (application
->priv
->impl
,
1433 action_name
, parameter
,
1434 get_platform_data (application
));
1437 g_action_group_activate_action (application
->priv
->actions
,
1438 action_name
, parameter
);
1442 g_application_action_group_iface_init (GActionGroupInterface
*iface
)
1444 iface
->has_action
= g_application_has_action
;
1445 iface
->list_actions
= g_application_list_actions
;
1447 iface
->get_action_enabled
= g_application_get_action_enabled
;
1448 iface
->get_action_parameter_type
= g_application_get_action_parameter_type
;
1449 iface
->get_action_state_type
= g_application_get_action_state_type
;
1450 iface
->get_action_state
= g_application_get_action_state
;
1451 iface
->change_action_state
= g_application_change_action_state
;
1452 iface
->activate_action
= g_application_activate_action
;
1456 /* vim:set foldmethod=marker: */