From ce3dddb62200fdcc97cc0aa4ec47400e94d99d36 Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Tue, 18 Sep 2012 10:14:35 -0400 Subject: [PATCH] GApplication: document differences from libunique People implementing GApplication often waste a lot of time by trying to use it as if it were libunique. Add a note to the docs about the difference. --- gio/gapplication.c | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/gio/gapplication.c b/gio/gapplication.c index 1172a591f..5f922d115 100644 --- a/gio/gapplication.c +++ b/gio/gapplication.c @@ -72,6 +72,19 @@ * applications this is the 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 + * uniqueness libraries (such as libunique) in important ways. The + * application is not expected to manually register itself and check if + * it is the primary instance. Instead, the main() + * function of a #GApplication should do very little more than + * instantiating the application instance, possibly connecting signal + * handlers, then calling g_application_run(). All checks for + * uniqueness are done internally. If the application is the primary + * instance then the startup signal is emitted and the mainloop runs. + * If the application is not the primary instance then a signal is sent + * to the primary 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.