![]() |
![]() |
![]() |
GTK+ 3 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Signals |
#include <gtk/gtk.h> struct GtkApplication; GtkApplication * gtk_application_new (const gchar *application_id
,GApplicationFlags flags
); void gtk_application_add_window (GtkApplication *application
,GtkWindow *window
); void gtk_application_remove_window (GtkApplication *application
,GtkWindow *window
); GList * gtk_application_get_windows (GtkApplication *application
); GMenuModel * gtk_application_get_app_menu (GtkApplication *application
); void gtk_application_set_app_menu (GtkApplication *application
,GMenuModel *model
); GMenuModel * gtk_application_get_menubar (GtkApplication *application
); void gtk_application_set_menubar (GtkApplication *application
,GMenuModel *model
);
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 GTK+ initialization, application uniqueness, provides some basic scriptability and desktop shell integration by exporting actions and menus and manages a list of toplevel windows whose life-cycle is automatically tied to the life-cycle of your application.
While GtkApplication works fine with plain GtkWindows, it is recommended to use it together with GtkApplicationWindow.
When GDK threads are enabled, GtkApplication will acquire the GDK
lock when invoking actions that arrive from other processes. The GDK
lock is not touched for local action invocations. In order to have
actions invoked in a predictable context it is therefore recommended
that the GDK lock be held while invoking actions locally with
g_action_group_activate_action()
. The same applies to actions
associated with GtkApplicationWindow and to the 'activate' and
'open' GApplication methods.
To set an application menu on a GtkApplication, use
g_application_set_app_menu()
. The GMenuModel that this function
expects is usually constructed using GtkBuilder, as seen in the
following example. To set a menubar that will be automatically picked
up by GApplicationWindows, use g_application_set_menubar()
. GTK+
makes these menus appear as expected, depending on the platform
the application is running on.
Example 109. 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 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 |
#include <stdlib.h> #include <gtk/gtk.h> static void activate_toggle (GSimpleAction *action, GVariant *parameter, gpointer user_data) { GVariant *state; state = g_action_get_state (G_ACTION (action)); g_action_change_state (G_ACTION (action), g_variant_new_boolean (!g_variant_get_boolean (state))); g_variant_unref (state); } static void change_fullscreen_state (GSimpleAction *action, GVariant *state, gpointer user_data) { if (g_variant_get_boolean (state)) gtk_window_fullscreen (user_data); else gtk_window_unfullscreen (user_data); g_simple_action_set_state (action, state); } static GtkClipboard * get_clipboard (GtkWidget *widget) { return gtk_widget_get_clipboard (widget, gdk_atom_intern_static_string ("CLIPBOARD")); } static void window_copy (GSimpleAction *action, GVariant *parameter, gpointer user_data) { GtkWindow *window = GTK_WINDOW (user_data); GtkTextView *text = g_object_get_data ((GObject*)window, "bloatpad-text"); gtk_text_buffer_copy_clipboard (gtk_text_view_get_buffer (text), get_clipboard ((GtkWidget*) text)); } static void window_paste (GSimpleAction *action, GVariant *parameter, gpointer user_data) { GtkWindow *window = GTK_WINDOW (user_data); GtkTextView *text = g_object_get_data ((GObject*)window, "bloatpad-text"); gtk_text_buffer_paste_clipboard (gtk_text_view_get_buffer (text), get_clipboard ((GtkWidget*) text), NULL, TRUE); } static GActionEntry win_entries[] = { { "copy", window_copy, NULL, NULL, NULL }, { "paste", window_paste, NULL, NULL, NULL }, { "fullscreen", activate_toggle, NULL, "false", change_fullscreen_state } }; static void new_window (GApplication *app, GFile *file) { GtkWidget *window, *grid, *scrolled, *view; window = gtk_application_window_new (GTK_APPLICATION (app)); gtk_window_set_default_size ((GtkWindow*)window, 640, 480); g_action_map_add_action_entries (G_ACTION_MAP (window), win_entries, G_N_ELEMENTS (win_entries), window); gtk_window_set_title (GTK_WINDOW (window), "Bloatpad"); grid = gtk_grid_new (); gtk_container_add (GTK_CONTAINER (window), grid); scrolled = gtk_scrolled_window_new (NULL, NULL); gtk_widget_set_hexpand (scrolled, TRUE); gtk_widget_set_vexpand (scrolled, TRUE); view = gtk_text_view_new (); g_object_set_data ((GObject*)window, "bloatpad-text", view); gtk_container_add (GTK_CONTAINER (scrolled), view); gtk_grid_attach (GTK_GRID (grid), scrolled, 0, 0, 1, 1); if (file != NULL) { gchar *contents; gsize length; if (g_file_load_contents (file, NULL, &contents, &length, NULL, NULL)) { GtkTextBuffer *buffer; buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view)); gtk_text_buffer_set_text (buffer, contents, length); g_free (contents); } } gtk_widget_show_all (GTK_WIDGET (window)); } static void bloat_pad_activate (GApplication *application) { new_window (application, NULL); } static void bloat_pad_open (GApplication *application, GFile **files, gint n_files, const gchar *hint) { gint i; for (i = 0; i < n_files; i++) new_window (application, files[i]); } typedef GtkApplication BloatPad; typedef GtkApplicationClass BloatPadClass; G_DEFINE_TYPE (BloatPad, bloat_pad, GTK_TYPE_APPLICATION) static void bloat_pad_finalize (GObject *object) { G_OBJECT_CLASS (bloat_pad_parent_class)->finalize (object); } static void new_activated (GSimpleAction *action, GVariant *parameter, gpointer user_data) { g_application_activate (user_data); } static void show_about (GSimpleAction *action, GVariant *parameter, gpointer user_data) { gtk_show_about_dialog (NULL, "program-name", "Bloatpad", "title", "About Bloatpad", "comments", "Not much to say, really.", NULL); } static void quit_app (GSimpleAction *action, GVariant *parameter, gpointer user_data) { GList *list, *next; GtkWindow *win; g_print ("Going down...\n"); list = gtk_application_get_windows (GTK_APPLICATION (g_application_get_default ())); while (list) { win = list->data; next = list->next; gtk_widget_destroy (GTK_WIDGET (win)); list = next; } } static GActionEntry app_entries[] = { { "new", new_activated, NULL, NULL, NULL }, { "about", show_about, NULL, NULL, NULL }, { "quit", quit_app, NULL, NULL, NULL }, }; static void bloat_pad_startup (GApplication *application) { GtkBuilder *builder; G_APPLICATION_CLASS (bloat_pad_parent_class) ->startup (application); g_action_map_add_action_entries (G_ACTION_MAP (application), app_entries, G_N_ELEMENTS (app_entries), application); builder = gtk_builder_new (); gtk_builder_add_from_string (builder, "<interface>" " <menu id='app-menu'>" " <section>" " <item label='_New Window' action='app.new' accel='<Primary>n'/>" " </section>" " <section>" " <item label='_About Bloatpad' action='app.about'/>" " </section>" " <section>" " <item label='_Quit' action='app.quit' accel='<Primary>q'/>" " </section>" " </menu>" " <menu id='menubar'>" " <submenu label='_Edit'>" " <section>" " <item label='_Copy' action='win.copy' accel='<Primary>c'/>" " <item label='_Paste' action='win.paste' accel='<Primary>v'/>" " </section>" " </submenu>" " <submenu label='_View'>" " <section>" " <item label='_Fullscreen' action='win.fullscreen'/>" " </section>" " </submenu>" " </menu>" "</interface>", -1, NULL); gtk_application_set_app_menu (GTK_APPLICATION (application), G_MENU_MODEL (gtk_builder_get_object (builder, "app-menu"))); gtk_application_set_menubar (GTK_APPLICATION (application), G_MENU_MODEL (gtk_builder_get_object (builder, "menubar"))); g_object_unref (builder); } static void bloat_pad_init (BloatPad *app) { } static void bloat_pad_class_init (BloatPadClass *class) { GApplicationClass *application_class = G_APPLICATION_CLASS (class); GObjectClass *object_class = G_OBJECT_CLASS (class); application_class->startup = bloat_pad_startup; application_class->activate = bloat_pad_activate; application_class->open = bloat_pad_open; object_class->finalize = bloat_pad_finalize; } BloatPad * bloat_pad_new (void) { g_type_init (); return g_object_new (bloat_pad_get_type (), "application-id", "org.gtk.Test.bloatpad", "flags", G_APPLICATION_HANDLES_OPEN, NULL); } int main (int argc, char **argv) { BloatPad *bloat_pad; int status; bloat_pad = bloat_pad_new (); gtk_application_add_accelerator (GTK_APPLICATION (bloat_pad), "F11", "win.fullscreen", NULL); status = g_application_run (G_APPLICATION (bloat_pad), argc, argv); g_object_unref (bloat_pad); return status; } |
GtkApplication * gtk_application_new (const gchar *application_id
,GApplicationFlags flags
);
Creates a new GtkApplication instance.
This function calls g_type_init()
for you. gtk_init()
is called
as soon as the application gets registered as the primary instance.
Note that commandline arguments are not passed to gtk_init()
.
All GTK+ functionality that is available via commandline arguments
can also be achieved by setting suitable environment variables
such as <envvar>G_DEBUG</envvar>, so this should not be a big
problem. If you absolutely must support GTK+ commandline arguments,
you can explicitly call gtk_init()
before creating the application
instance.
The application id must be valid. See g_application_id_is_valid()
.
|
the application id |
|
the application flags |
Returns : |
a new GtkApplication instance |
void gtk_application_add_window (GtkApplication *application
,GtkWindow *window
);
Adds a window from application
.
This call is equivalent to setting the "application"
property of window
to application
.
Normally, the connection between the application and the window
will remain until the window is destroyed, but you can explicitly
remove it with gtk_application_remove_window()
.
GTK+ will keep the application running as long as it has any windows.
|
a GtkApplication |
|
a GtkWindow |
Since 3.0
void gtk_application_remove_window (GtkApplication *application
,GtkWindow *window
);
Remove a window from application
.
If window
belongs to application
then this call is equivalent to
setting the "application" property of window
to
NULL
.
The application may stop running as a result of a call to this function.
|
a GtkApplication |
|
a GtkWindow |
Since 3.0
GList * gtk_application_get_windows (GtkApplication *application
);
Gets a list of the GtkWindows associated with application
.
The list is sorted by most recently focused window, such that the first element is the currently focused window. (Useful for choosing a parent for a transient window.)
The list that is returned should not be modified in any way. It will only remain valid until the next focus change or window creation or deletion.
|
a GtkApplication |
Returns : |
a GList of GtkWindow. [element-type GtkWindow][transfer none] |
Since 3.0
GMenuModel * gtk_application_get_app_menu (GtkApplication *application
);
Returns the menu model that has been set with
g_application_set_app_menu()
.
|
a GtkApplication |
Returns : |
the application menu of application
|
Since 3.4
void gtk_application_set_app_menu (GtkApplication *application
,GMenuModel *model
);
Sets or unsets the application menu for application
.
The application menu is a single menu containing items that typically impact the application as a whole, rather than acting on a specific window or document. For example, you would expect to see "Preferences" or "Quit" in an application menu, but not "Save" or "Print".
If supported, the application menu will be rendered by the desktop environment.
|
a GtkApplication |
|
a GMenuModel, or NULL . [allow-none]
|
Since 3.4
GMenuModel * gtk_application_get_menubar (GtkApplication *application
);
Returns the menu model that has been set with
g_application_set_menubar()
.
|
a GtkApplication |
Returns : |
the menubar for windows of application
|
Since 3.4
void gtk_application_set_menubar (GtkApplication *application
,GMenuModel *model
);
Sets or unsets the menubar for windows of application
.
This is a menubar in the traditional sense.
Depending on the desktop environment, this may appear at the top of each window, or at the top of the screen. In some environments, if both the application menu and the menubar are set, the application menu will be presented as if it were the first item of the menubar. Other environments treat the two as completely separate -- for example, the application menu may be rendered by the desktop shell while the menubar (if set) remains in each individual window.
|
a GtkApplication |
|
a GMenuModel, or NULL . [allow-none]
|
Since 3.4
"window-added"
signalvoid user_function (GtkApplication *application,
GtkWindow *window,
gpointer user_data) : Run First
Emitted when a GtkWindow is added to application
through
gtk_application_add_window()
.
|
the GtkApplication which emitted the signal |
|
the newly-added GtkWindow |
|
user data set when the signal handler was connected. |
Since 3.2
"window-removed"
signalvoid user_function (GtkApplication *application,
GtkWindow *window,
gpointer user_data) : Run First
Emitted when a GtkWindow is removed from application
,
either as a side-effect of being destroyed or explicitly
through gtk_application_remove_window()
.
|
the GtkApplication which emitted the signal |
|
the GtkWindow that is being removed |
|
user data set when the signal handler was connected. |
Since 3.2