![]() |
![]() |
![]() |
GTK+ Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Signals |
#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
); const GSList * gtk_application_get_windows (GtkApplication *app
); GtkWindow * gtk_application_create_window (GtkApplication *app
);
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 61. 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; } |
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()
.
|
System-dependent application identifier |
|
System argument count. [allow-none][inout] |
|
System argument vector. [allow-none][inout] |
Returns : |
A newly-referenced GtkApplication. [transfer full] |
Since 3.0
void gtk_application_run (GtkApplication *app
);
Runs the main loop; see g_application_run()
.
The default implementation for GtkApplication uses gtk_main()
.
|
a GtkApplication |
Since 3.0
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.
|
a GtkApplication |
Since 3.0
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:
It is an error to call this function more than once.
|
A GtkApplication |
|
A GtkActionGroup |
Since 3.0
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.
|
a GtkApplication |
Returns : |
The default GtkWindow for this application. [transfer none] |
Since 3.0
void gtk_application_add_window (GtkApplication *app
,GtkWindow *window
);
Adds a window to the GtkApplication.
If all the windows managed by GtkApplication are closed, the
GtkApplication will call gtk_application_quit()
, and quit
the application.
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()
.
|
a GtkApplication |
|
a toplevel window to add to app
|
Since 3.0
const GSList * gtk_application_get_windows (GtkApplication *app
);
Retrieves the list of windows previously registered with
gtk_application_create_window()
or gtk_application_add_window()
.
|
a GtkApplication |
Returns : |
A pointer
to the list of GtkWindows registered by this application,
or NULL . The returned GSList is owned by the GtkApplication
and it should not be modified or freed directly. [element-type GtkWindow][transfer none GtkWindow]
|
Since 3.0
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.
|
a GtkApplication |
Returns : |
the newly created application GtkWindow. [transfer none] |
Since 3.0
"action"
signalvoid 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.
|
the object on which the signal is emitted |
|
The name of the activated action |
|
user data set when the signal handler was connected. |
Since 3.0
"activated"
signalvoid 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
.
|
A GVariant with the signature "aay" |
|
user data set when the signal handler was connected. |
Since 3.0
"quit"
signalgboolean 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. It is possible to override the default handler
by simply returning TRUE
from a callback, e.g.:
1 2 3 4 5 6 7 8 9 10 11 12 13 |
static gboolean my_application_quit (GtkApplication *application) { /* if some_condition is TRUE, do not quit */ if (some_condition) return TRUE; /* this will cause the application to quit * return FALSE; } g_signal_connect (application, "quit", G_CALLBACK (my_application_quit), NULL); |
|
the object on which the signal is emitted |
|
user data set when the signal handler was connected. |
Returns : |
TRUE if the signal has been handled, FALSE to continue
signal emission
|
Since 3.0