luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-23 22:16:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

Brush up the GApplication docs

Browse Source 
Also, fix up inclusions, mark properties for translation, etc.
This commit is contained in:
Matthias Clasen 2010-10-23 00:40:13 +02:00
parent 210a77a07e
commit 79790b9278
7 changed files with 141 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
gio/gapplication.c
View File

@ -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 <string.h>
/**
* 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
* <firstterm>primary instance</firstterm>.
*
* Before using GApplication, you must choose an "application identifier".
* The expected form of an application identifier is very close to that of
* of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>.
* Examples include: "com.example.MyApp" "org.example.internal-apps.Calculator"
* For convenience, the restrictions on application identifiers are reproduced
* here:
* <itemizedlist>
* <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit.</listitem>
* <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least two elements).</listitem>
* <listitem>Application identifiers must not begin with a '.' (period) character.</listitem>
* <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
* <listitem>Application identifiers must not exceed 255 characters.</listitem>
* </itemizedlist>
*/
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 <emphasis>service</emphasis> to others).
*
* Since: 2.28
**/
int

2
gio/gapplication.h
View File

@ -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.

40
gio/gapplicationcommandline.c
View File

@ -19,8 +19,12 @@
* Authors: Ryan Lortie <desrt@desrt.ca>
*/
#include "config.h"
#include "gapplicationcommandline.h"
#include "glibintl.h"
#include <string.h>
#include <stdio.h>
@ -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 <varname>command-line</varname> 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 <varname>command-line</varname> 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.
*

2
gio/gdbuserror.c
View File

@ -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

8
gio/gioenums.h
View File

@ -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.
*

2
gio/gsimpleaction.c
View File

@ -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

2
gio/gsimpleactiongroup.c
View File

@ -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.