GtkApplication

GtkApplication — Application class

Synopsis

#include <gtk/gtk.h>

                    GtkApplication;
GtkApplication*     gtk_application_new                 (const gchar *appid,
                                                         gint *argc,
                                                         gchar ***argv);
void                gtk_application_run                 (GtkApplication *app);
void                gtk_application_quit                (GtkApplication *app);
void                gtk_application_set_action_group    (GtkApplication *app,
                                                         GtkActionGroup *group);
GtkWindow *         gtk_application_get_window          (GtkApplication *app);
void                gtk_application_add_window          (GtkApplication *app,
                                                         GtkWindow *window);
GtkWindow *         gtk_application_create_window       (GtkApplication *app);

Object Hierarchy

  GObject
   +----GApplication
         +----GtkApplication

Implemented Interfaces

GtkApplication implements GInitable.

Signals

  "action"                                         : Run First / No Recursion / Has Details
  "activated"                                      : Run Last
  "quit"                                           : Run Last

Description

GtkApplication is a class that handles many important aspects of a GTK+ application in a convenient fashion, without enforcing a one-size-fits-all application model.

Currently, GtkApplication handles application uniqueness, provides some basic scriptability by exporting 'actions', implements some standard actions itself (such as 'Quit') and provides a main window whose life-cycle is automatically tied to the life-cycle of your application.

Example 59. A simple application

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
#include <gtk/gtk.h>

static const char *builder_data =
"<interface>"
"<object class=\"GtkAboutDialog\" id=\"about_dialog\">"
"  <property name=\"program-name\">Example Application</property>"
"  <property name=\"website\">http://www.gtk.org</property>"
"</object>"
"<object class=\"GtkActionGroup\" id=\"actions\">"
"  <child>"
"      <object class=\"GtkAction\" id=\"About\">"
"          <property name=\"name\">About</property>"
"          <property name=\"stock_id\">gtk-about</property>"
"      </object>"
"  </child>"
"</object>"
"</interface>";

static GtkWidget *about_dialog;

static void
about_activate (GtkAction *action,
                gpointer   user_data)
{
  gtk_dialog_run (GTK_DIALOG (about_dialog));
  gtk_widget_hide (GTK_WIDGET (about_dialog));
}

int
main (int argc, char **argv)
{
  GtkApplication *app;
  GtkWindow *window;
  GtkBuilder *builder;
  GtkAction *action;
  GtkActionGroup *actions;

  app = gtk_application_new ("org.gtk.Example", &argc, &argv);
  builder = gtk_builder_new ();
  if (!gtk_builder_add_from_string (builder, builder_data, -1, NULL))
    g_error ("failed to parse UI");
  actions = GTK_ACTION_GROUP (gtk_builder_get_object (builder, "actions"));
  gtk_application_set_action_group (app, actions);

  action = gtk_action_group_get_action (actions, "About");
  g_signal_connect (action, "activate", G_CALLBACK (about_activate), app);

  about_dialog = GTK_WIDGET (gtk_builder_get_object (builder, "about_dialog"));

  gtk_builder_connect_signals (builder, app);
  g_object_unref (builder);

  window = gtk_application_get_window (app);
  gtk_container_add (GTK_CONTAINER (window), gtk_label_new ("Hello world"));
  gtk_widget_show_all (GTK_WIDGET (window));

  gtk_application_run (app);

  return 0;
}


Details

GtkApplication

typedef struct _GtkApplication GtkApplication;


gtk_application_new ()

GtkApplication*     gtk_application_new                 (const gchar *appid,
                                                         gint *argc,
                                                         gchar ***argv);

Create a new GtkApplication, or if one has already been initialized in this process, return the existing instance. This function will as a side effect initialize the display system; see gtk_init().

For the behavior if this application is running in another process, see g_application_new().

appid :

System-dependent application identifier

argc :

System argument count. [allow-none][inout]

argv :

System argument vector. [allow-none][inout]

Returns :

A newly-referenced GtkApplication. [transfer full]

Since 3.0


gtk_application_run ()

void                gtk_application_run                 (GtkApplication *app);

Runs the main loop; see g_application_run(). The default implementation for GtkApplication uses gtk_main().

app :

a GtkApplication

Since 3.0


gtk_application_quit ()

void                gtk_application_quit                (GtkApplication *app);

Request the application exit. This function invokes g_application_quit_with_data(), which normally will in turn cause app to emit "quit".

To control an application's quit behavior (for example, to ask for files to be saved), connect to the "quit" signal handler.

app :

a GtkApplication

Since 3.0


gtk_application_set_action_group ()

void                gtk_application_set_action_group    (GtkApplication *app,
                                                         GtkActionGroup *group);

Set group as this application's global action group. This will ensure the operating system interface uses these actions as follows:

  • In GNOME 2 this exposes the actions for scripting.
  • In GNOME 3, this function populates the application menu.
  • In Windows prior to version 7, this function does nothing.
  • In Windows 7, this function adds "Tasks" to the Jump List.
  • In Mac OS X, this function extends the Dock menu.

It is an error to call this function more than once.

app :

A GtkApplication

group :

A GtkActionGroup

Since 3.0


gtk_application_get_window ()

GtkWindow *         gtk_application_get_window          (GtkApplication *app);

A simple GtkApplication has a "default window". This window should act as the primary user interaction point with your application. The window returned by this function is of type GTK_WINDOW_TYPE_TOPLEVEL and its properties such as "title" and "icon-name" will be initialized as appropriate for the platform.

If the user closes this window, and your application hasn't created any other windows, the default action will be to call gtk_application_quit().

If your application has more than one toplevel window (e.g. an single-document-interface application with multiple open documents), or if you are constructing your toplevel windows yourself (e.g. using GtkBuilder), use gtk_application_create_window() or gtk_application_add_window() instead.

app :

a GtkApplication

Returns :

The default GtkWindow for this application. [transfer none]

Since 3.0


gtk_application_add_window ()

void                gtk_application_add_window          (GtkApplication *app,
                                                         GtkWindow *window);

Adds a window to the GtkApplication.

If the user closes all of the windows added to app, the default behaviour is to call gtk_application_quit().

If your application uses only a single toplevel window, you can use gtk_application_get_window(). If you are using a sub-class of GtkApplication you should call gtk_application_create_window() to let the GtkApplication instance create a GtkWindow and add it to the list of toplevels of the application. You should call this function only to add GtkWindows that you created directly using gtk_window_new().

app :

a GtkApplication

window :

a toplevel window to add to app

Since 3.0


gtk_application_create_window ()

GtkWindow *         gtk_application_create_window       (GtkApplication *app);

Creates a new GtkWindow for the application.

This function calls the GtkApplication::create_window() virtual function, which can be overridden by sub-classes, for instance to use GtkBuilder to create the user interface. After creating a new GtkWindow instance, it will be added to the list of toplevels associated to the application.

app :

a GtkApplication

Returns :

the newly created application GtkWindow. [transfer none]

Since 3.0

Signal Details

The "action" signal

void                user_function                      (GtkApplication *application,
                                                        gchar          *name,
                                                        gpointer        user_data)        : Run First / No Recursion / Has Details

This signal is emitted when an action is activated. The action name is passed as the first argument, but also as signal detail, so it is possible to connect to this signal for individual actions.

See also the "action-with-data" signal which may in turn trigger this signal.

The signal is never emitted for disabled actions.

application :

the object on which the signal is emitted

name :

The name of the activated action

user_data :

user data set when the signal handler was connected.

The "activated" signal

void                user_function                      (GtkApplication *arguments,
                                                        GVariant        arg1,
                                                        gpointer        user_data)      : Run Last

This signal is emitted when a non-primary process for a given application is invoked while your application is running; for example, when a file browser launches your program to open a file. The raw operating system arguments are passed in the variant arguments.

arguments :

A GVariant with the signature "aay"

user_data :

user data set when the signal handler was connected.

The "quit" signal

gboolean            user_function                      (GtkApplication *application,
                                                        gpointer        user_data)        : Run Last

This signal is emitted when a quit is initiated. See also the "quit-with-data" signal which may in turn trigger this signal.

The default handler for this signal exits the mainloop of the application.

application :

the object on which the signal is emitted

user_data :

user data set when the signal handler was connected.

Returns :

TRUE if the signal has been handled, FALSE to continue signal emission