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