From 79790b927840b1c2d389753c7237820d2f16899e Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 23 Oct 2010 00:40:13 +0200 Subject: [PATCH] Brush up the GApplication docs Also, fix up inclusions, mark properties for translation, etc. --- gio/gapplication.c | 124 +++++++++++++++++++++++++++++++++++------- gio/gapplication.h | 2 + gio/gapplicationcommandline.c | 40 +++++++++----- gio/gdbuserror.c | 2 +- gio/gioenums.h | 8 ++- gio/gsimpleaction.c | 2 +- gio/gsimpleactiongroup.c | 2 +- 7 files changed, 141 insertions(+), 39 deletions(-) diff --git a/gio/gapplication.c b/gio/gapplication.c index 35ab451..c81c28c 100644 --- a/gio/gapplication.c +++ b/gio/gapplication.c @@ -20,6 +20,8 @@ */ /* Prologue {{{1 */ +#include "config.h" + #include "gapplication.h" #include "gapplicationcommandline.h" @@ -31,8 +33,45 @@ #include "gioenums.h" #include "gfile.h" +#include "glibintl.h" + #include +/** + * SECTION: gapplication + * @title: GApplication + * @short_description: Core application class + * + * A #GApplication is the foundation of an application, unique for a + * given application identifier. The GApplication class wraps some + * low-level platform-specific services and is intended to act as the + * foundation for higher-level application classes such as + * #GtkApplication or #MxApplication. In general, you should not use + * this class outside of a higher level framework. + * + * One of the core features that GApplication provides is process + * uniqueness, in the context of a "session". The session concept is + * platform-dependent, but corresponds roughly to a graphical desktop + * login. When your application is launched again, its arguments + * are passed through platform communication to the already running + * program. The already running instance of the program is called the + * primary instance. + * + * Before using GApplication, you must choose an "application identifier". + * The expected form of an application identifier is very close to that of + * of a DBus bus name. + * Examples include: "com.example.MyApp" "org.example.internal-apps.Calculator" + * 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 must contain at least one '.' (period) character (and thus at least two elements). + * Application identifiers must not begin with a '.' (period) character. + * Application identifiers must not contain consecutive '.' (period) characters. + * Application identifiers must not exceed 255 characters. + * + */ + struct _GApplicationPrivate { GApplicationFlags flags; @@ -410,54 +449,95 @@ g_application_class_init (GApplicationClass *class) class->run_mainloop = g_application_real_run_mainloop; g_object_class_install_property (object_class, PROP_APPLICATION_ID, - g_param_spec_string ("application-id", "application identifier", - "Unique identifier for the application", + g_param_spec_string ("application-id", + P_("Application identifier"), + P_("The unique identifier for the application"), NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (object_class, PROP_FLAGS, - g_param_spec_flags ("flags", "application flags", - "Flags specifying the behaviour of the application", - G_TYPE_APPLICATION_FLAGS, G_APPLICATION_FLAGS_NONE, - G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + g_param_spec_flags ("flags", + P_("Application flags"), + P_("Flags specifying the behaviour of the application"), + G_TYPE_APPLICATION_FLAGS, G_APPLICATION_FLAGS_NONE, + G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (object_class, PROP_IS_REGISTERED, - g_param_spec_boolean ("is-registered", "is registered", - "If g_application_register() has been called", + g_param_spec_boolean ("is-registered", + P_("Is registered"), + P_("If g_application_register() has been called"), FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (object_class, PROP_IS_REMOTE, - g_param_spec_boolean ("is-remote", "is remote", - "If this application instance is remote", + g_param_spec_boolean ("is-remote", + P_("Is remote"), + P_("If this application instance is remote"), FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (object_class, PROP_INACTIVITY_TIMEOUT, - g_param_spec_boolean ("inactivity-timeout", "inactivity timeout", - "time (ms) to stay alive after becoming idle", + g_param_spec_boolean ("inactivity-timeout", + P_("Inactivity timeout"), + P_("Iime (ms) to stay alive after becoming idle"), FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (object_class, PROP_ACTION_GROUP, - g_param_spec_object ("action-group", "action group", - "the group of actions that the application exports", + g_param_spec_object ("action-group", + P_("Action group"), + P_("The group of actions that the application exports"), G_TYPE_ACTION_GROUP, G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)); + /** + * GApplication::startup: + * @application: the application + * + * The ::startup signal is emitted on the primary instance immediately + * after registration. See g_activation_register(). + */ g_application_signals[SIGNAL_STARTUP] = g_signal_new ("startup", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GApplicationClass, startup), NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + /** + * GApplication::activate: + * @application: the application + * + * The ::activate signal is emitted on the primary instance when an + * activation occurs. See g_application_activate(). + */ g_application_signals[SIGNAL_ACTIVATE] = g_signal_new ("activate", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GApplicationClass, activate), NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GApplication::open: + * @application: the application + * @files: an array of #GFile objects + * @n_files: the length of @files + * @hint: a hint provided by the calling instance + * + * The ::open signal is emitted on the primary instance when there are + * 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_STRUCT_OFFSET (GApplicationClass, open), NULL, NULL, _gio_marshal_VOID__POINTER_INT_STRING, G_TYPE_NONE, 3, G_TYPE_POINTER, G_TYPE_INT, G_TYPE_STRING); + /** + * GApplication::command-line: + * @application: the application + * @command_line: a #GApplicationCommandLine representing the + * passed commandline + * + * The ::command-line signal is emitted on the primary instance when + * a commandline is not handled locally. See g_application_run() for + * more information. + */ g_application_signals[SIGNAL_COMMAND_LINE] = g_signal_new ("command-line", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GApplicationClass, command_line), @@ -938,7 +1018,7 @@ g_application_activate (GApplication *application) * for this functionality, you should use "". * * The application must be registered before calling this function and - * it must have the %G_APPLICATION_CAN_OPEN flag set. The open() + * it must have the %G_APPLICATION_HANDLES_OPEN flag set. The open() * virtual function should also be implemented in order for anything * meaningful to happen. * @@ -980,11 +1060,11 @@ g_application_open (GApplication *application, * * First, the handle_command_line() virtual function is invoked. This * function always runs on the local instance. If that function returns - * %FALSE then the application is registered and the command_line() - * virtual function is invoked in the primary instance (which may or may - * not be this instance). + * %FALSE then the application is registered and the #GApplication::command-line + * signal is emitted in the primary instance (which may or may not be + * this instance). * - * If the application has the %G_APPLICATION_REMOTE_COMMAND_LINE + * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE * flag set then the default implementation of handle_command_line() * always returns %FALSE immediately, resulting in the commandline * always being handled in the primary instance. @@ -995,7 +1075,7 @@ g_application_open (GApplication *application, * to register the application. If that works, then the command line * arguments are inspected. If no commandline arguments are given, then * g_application_activate() is called. If commandline arguments are - * given and the %G_APPLICATION_CAN_OPEN flags is set then they + * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they * are assumed to be filenames and g_application_open() is called. * * If you are interested in doing more complicated local handling of the @@ -1006,6 +1086,10 @@ g_application_open (GApplication *application, * non-zero then the mainloop is run until the use count falls to zero, * at which point 0 is returned. * + * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at + * use count of zero is delayed for a while (ie: the instance stays + * around to provide its service to others). + * * Since: 2.28 **/ int diff --git a/gio/gapplication.h b/gio/gapplication.h index 0974019..524a7e2 100644 --- a/gio/gapplication.h +++ b/gio/gapplication.h @@ -64,6 +64,8 @@ struct _GApplication * @startup: invoked on the primary instance immediately after registration * @activate: invoked on the primary instance when an activation occurs * @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. The * virtual function has the chance to inspect (and possibly replace) the list of command line arguments. See * g_application_run() for more information. diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c index 3b28525..53be6a1 100644 --- a/gio/gapplicationcommandline.c +++ b/gio/gapplicationcommandline.c @@ -19,8 +19,12 @@ * Authors: Ryan Lortie */ +#include "config.h" + #include "gapplicationcommandline.h" +#include "glibintl.h" + #include #include @@ -30,12 +34,12 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC * SECTION:gapplicationcommandline * @title: GApplicationCommandLine * @short_description: A class representing a command-line invocation of - * this application. + * an application * @see_also: #GApplication * * #GApplicationCommandLine represents a command-line invocation of - * containing application. It is created by #GApplication and emitted - * in the command-line signal and virtual function. + * an application. It is created by #GApplication and emitted + * in the #GApplication::command-line signal and virtual function. * * The class contains the list of arguments that the program was invoked * with. It is also possible to query if the commandline invocation was @@ -102,8 +106,10 @@ g_application_command_line_real_printerr_literal (GApplicationCommandLine *cmdli } static void -g_application_command_line_get_property (GObject *object, guint prop_id, - GValue *value, GParamSpec *pspec) +g_application_command_line_get_property (GObject *object, + guint prop_id, + GValue *value, + GParamSpec *pspec) { GApplicationCommandLine *cmdline = G_APPLICATION_COMMAND_LINE (object); @@ -190,22 +196,26 @@ g_application_command_line_class_init (GApplicationCommandLineClass *class) class->print_literal = g_application_command_line_real_print_literal; g_object_class_install_property (object_class, PROP_ARGUMENTS, - g_param_spec_variant ("arguments", "commandline arguments", - "the commandline that caused this cmdline", + g_param_spec_variant ("arguments", + P_("Commandline arguments"), + P_("The commandline that caused this ::command-line signal emission"), G_VARIANT_TYPE_BYTESTRING_ARRAY, NULL, G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (object_class, PROP_PLATFORM_DATA, - g_param_spec_variant ("platform-data", "platform data", - "platform-specific data for the cmdline", + g_param_spec_variant ("platform-data", + P_("Platform data"), + P_("Platform-specific data for the commandline"), G_VARIANT_TYPE ("a{sv}"), NULL, G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (object_class, PROP_IS_REMOTE, - g_param_spec_boolean ("is-remote", "is remote", - "TRUE if this is a remote cmdline", FALSE, + g_param_spec_boolean ("is-remote", + P_("Is remote"), + P_("TRUE if this is a remote commandline"), + FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); g_type_class_add_private (class, sizeof (GApplicationCommandLinePrivate)); @@ -229,8 +239,8 @@ g_application_command_line_class_init (GApplicationCommandLineClass *class) * Since: 2.28 **/ gchar ** -g_application_command_line_get_arguments (GApplicationCommandLine *cmdline, - int *argc) +g_application_command_line_get_arguments (GApplicationCommandLine *cmdline, + int *argc) { gchar **argv; gsize len; @@ -248,7 +258,7 @@ g_application_command_line_get_arguments (GApplicationCommandLine *cmdline, /** * g_application_command_line_get_cwd: * @cmdline: a #GApplicationCommandLine - * + * * Gets the working directory of the command line invocation. The * string may contain non-utf8 data. * @@ -365,7 +375,7 @@ g_application_command_line_printerr (GApplicationCommandLine *cmdline, * Sets the exit status that will be used when the invoking process * exits. * - * The return value of the command-line signal is + * The return value of the #GApplication::command-line signal is * passed to this function when the handler returns. This is the usual * way of setting the exit status. * diff --git a/gio/gdbuserror.c b/gio/gdbuserror.c index 5e438ef..064c67b 100644 --- a/gio/gdbuserror.c +++ b/gio/gdbuserror.c @@ -36,7 +36,7 @@ /** * SECTION:gdbuserror * @title: GDBusError - * @short_description: Mapping D-Bus errors to and from #GError + * @short_description: Mapping D-Bus errors to and from GError * @include: gio/gio.h * * All facilities that return errors from remote methods (such as diff --git a/gio/gioenums.h b/gio/gioenums.h index 98551cc..eba19eb 100644 --- a/gio/gioenums.h +++ b/gio/gioenums.h @@ -1219,7 +1219,13 @@ typedef enum /** * GApplicationFlags: * @G_APPLICATION_FLAGS_NONE: Default - * @G_APPLICATION_FLAGS_HANDLE_OPEN: This application handles opening files. + * @G_APPLICATION_IS_SERVICE: Stay around for a while when the use count + * falls to zero. + * @G_APPLICATION_IS_LAUNCHER: Don't try to become the primary instance. + * @G_APPLICATION_HANDLES_OPEN: This application handles opening files (in the + * primary instance) + * @G_APPLICATION_HANDLES_COMMAND_LINE: This application handles command lines + * (in the primary instance) * * Flags used to define the behaviour of a #GApplication. * diff --git a/gio/gsimpleaction.c b/gio/gsimpleaction.c index fbecde4..e0eebaa 100644 --- a/gio/gsimpleaction.c +++ b/gio/gsimpleaction.c @@ -33,7 +33,7 @@ G_DEFINE_TYPE_WITH_CODE (GSimpleAction, g_simple_action, G_TYPE_OBJECT, /** * SECTION:gsimpleaction * @title: GSimpleAction - * @short_description: a simple #GSimpleAction + * @short_description: a simple GSimpleAction * * A #GSimpleAction is the obvious simple implementation of the #GSimpleAction * interface. This is the easiest way to create an action for purposes of diff --git a/gio/gsimpleactiongroup.c b/gio/gsimpleactiongroup.c index 6482b0b..940a081 100644 --- a/gio/gsimpleactiongroup.c +++ b/gio/gsimpleactiongroup.c @@ -25,7 +25,7 @@ /** * SECTION:gsimpleactiongroup * @title: GSimpleActionGroup - * @short_description: a simple #GActionGroup implementation + * @short_description: a simple GActionGroup implementation * * #GSimpleActionGroup is a hash table filled with #GAction objects, * implementing the #GActionGroup interface. -- 2.7.4