GtkApplication

GtkApplication — Application class

Synopsis

#include <gtk/gtk.h>

                    GtkApplication;
GtkApplication*     gtk_application_new                 (gint *argc,
                                                         gchar ***argv,
                                                         const gchar *appid);
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);

Object Hierarchy

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

Signals

  "activated"                                      : 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 (&argc, &argv, "org.gtk.Example");
  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                 (gint *argc,
                                                         gchar ***argv,
                                                         const gchar *appid);

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().

argc :

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

argv :

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

appid :

System-dependent application identifier

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. By default, this method will exit the main loop; see gtk_main_quit().

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_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().

app :

a GtkApplication

window :

a toplevel window to add to app

Since 3.0

Signal Details

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.