GtkApplication is the base class of a GTK Application.
The philosophy of
GtkApplication is that applications are interested in
being told what needs to happen, when it needs to happen, in response to actions
from the user. The exact mechanism by which the operating system starts
applications is uninteresting.
To this end,
GtkApplication exposes a set of signals (or virtual functions)
that an application should respond to:
startup: sets up the application when it first starts
shutdown: performs shutdown tasks
activate: shows the default first window of the application (like a new document). This corresponds to the application being launched by the desktop environment.
open: opens files and shows them in a new window. This corresponds to someone trying to open a document (or documents) using the application from the file browser, or similar.
When your application starts, the
startup signal will be fired. This gives
you a chance to perform initialisation tasks that are not directly related to
showing a new window. After this, depending on how the application is started,
open will be called next.
GtkApplication defaults to applications being single-instance. If the user
attempts to start a second instance of a single-instance application then
GtkApplication will signal the first instance and you will receive additional
activate or open signals. In this case, the second instance will exit
immediately, without calling
All startup initialisation should be done in startup. This avoids wasting work in the second-instance case where the program just exits immediately.
The application will continue to run for as long as it needs to. This is usually
for as long as there are any open windows. You can additionally force the
application to stay alive using
On shutdown, you receive a
shutdown signal where you can do any necessary
cleanup tasks (such as saving files to disk).
You main entry point for your application should only create a
GtkApplication instance, set up the signal handlers, and then call
Primary vs. local instance#
The “primary instance” of an application is the first instance of it that was run. A “remote instance” is another instance that is started that is not the primary instance. The term “local instance” is used to refer to the current process which may or may not be the primary instance.
GtkApplication only ever emits signals in the primary instance. Calls to
GtkApplication API can be made in primary or remote instances (and are made
from the vantage of being the “local instance”). In the case that the local
instance is the primary instance, function calls on
result in signals being emitted locally, in the primary instance. In the case
that the local instance is a remote instance, function calls result in messages
being sent to the primary instance and signals being emitted there.
For example, calling
g_application_activate() on the primary instance will
activate signal. Calling it on a remote instance will result in a
message being sent to the primary instance and it will emit
You rarely need to know if the local instance is primary or remote. In almost
all cases, you should just call the
GtkApplication method you are interested
in and either have it be forwarded or handled locally, as appropriate.
An application can register a set of actions that it supports in addition to the
default activate and open. Actions are added to the application with the
GActionMap interface and invoked or queried with the
on the primary instance will activate the named action in the current process.
g_action_group_activate_action() on a remote instance will send a
message to the primary instance, causing the action to be activated there.
Dealing with the command line#
GtkApplication will assume that arguments passed on the command
line are files to be opened. If no arguments are passed, then it assumes that an
application is being launched to show its main window or an empty document. In
the case that files were given, you will receive these files (in the form of
GFile) from the open signal. Otherwise you will receive an activate signal.
It is recommended that new applications make use of this default handling of
command line arguments.
If you want to deal with command line arguments in more advanced ways, there are several (complementary) mechanisms by which you can do this.
handle-local-options signal will be emitted and the signal
handler gets a dictionary with the parsed options. To make use of this, you need
to register your options with
signal handler can return a non-negative value to end the process with this exit
code, or a negative value to continue with the regular handling of commandline
options. A popular use of for this signal is to implement a
argument that works without communicating with a remote instance.
handle-local-options is not flexible enough for your needs, you can
local_command_line virtual function to take over the handling
of command line arguments in the local instance entirely. If you do so, you will
be responsible for registering the application, and for handling a
argument (the default
local_command_line function does this for you).
It is also possible to invoke actions from
local_command_line in response to command line arguments. For example, a
mail client may choose to map the
--compose command line argument to an
invocation of its
compose action. This is done by calling
g_action_group_activate_action() from the
implementation. In the case that the command line being processed is in the
primary instance then the
compose action is invoked locally. In the case
that it is a remote instance, the action invocation is forwarded to the primary
It is possible to use action activations instead of
It is perfectly reasonable that an application could start without an
activate signal ever being emitted. The
activate signal is only
supposed to be the default “started with no options” signal. Actions are
meant to be used for anything else.
Some applications may wish to perform even more advanced handling of command
lines, including controlling the life cycle of the remote instance and its exit
status once it quits as well as forwarding the entire contents of the command
line arguments, the environment and even forwarding standard input, output, and
error streams. This can be accomplished using
G_APPLICATION_HANDLES_COMMAND_LINE and the