[77:7] extends: object
A high-level API for writing applications. GtkApplication supports many
aspects of writing a GTK application in a convenient fashion, without
enforcing a one-size-fits-all model. Currently, it handles GTK
initialization, application uniqueness, session management, 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 [class@Gtk.Window]s, it is recommended
to use it together with [class@Gtk.ApplicationWindow]. ## Initialization A
typical GtkApplication will create a window in its
[signal@GIO.Application::activate], [signal@GIO.Application::open] or
[signal@GIO.Application::command-line] handlers. Note that all of these
signals may be emitted multiple times, so handlers must be careful to take
existing windows into account. A typical ::activate handler should look like
this: static void activate (GApplication *gapp) { GtkApplication *app = GTK_APPLICATION (gapp); GtkWindow *window; window = gtk_application_get_active_window (app); if (!window) window = create_window (app); gtk_window_present (window); } ## Automatic resources
GtkApplication will automatically load menus from the GtkBuilder resource
located at "gtk/menus.ui", relative to the application's resource base path
(see [method@Gio.Application.set_resource_base_path]). The menu with the ID
"menubar" is taken as the application's menubar. Additional menus (most
interesting submenus) can be named and accessed via
[method@Gtk.Application.get_menu_by_id] which allows for dynamic population
of a part of the menu structure. Note that automatic resource loading uses
the resource base path that is set at construction time and will not work if
the resource base path is changed at a later time. It is also possible to
provide the menubar manually using [method@Gtk.Application.set_menubar].
GtkApplication will also automatically setup an icon search path for the
default icon theme by appending "icons" to the resource base path. This
allows your application to easily store its icons as resources. See
[method@Gtk.IconTheme.add_resource_path] for more information. If there is a
resource located at gtk/help-overlay.ui which defines a
[class@Gtk.ShortcutsWindow] with ID help_overlay then GtkApplication
associates an instance of this shortcuts window with each
[class@Gtk.ApplicationWindow] and sets up the keyboard accelerator
Control+? to open it. To create a menu item that
displays the shortcuts window, associate the item with the action
win.show-help-overlay. GtkApplication will also automatically set the
application id as the default window icon. Use
[func@Gtk.Window.set_default_icon_name] or [property@Gtk.Window:icon-name] to
override that behavior. ## State saving GtkApplication registers with a
session manager if possible and offers various functionality related to the
session life-cycle, such as state saving. State-saving functionality can be
enabled by setting the [property@Gtk.Application:support-save] property to
true. In order to save and restore per-window state, applications must
connect to the [signal@Gtk.Application::restore-window] signal and handle the
[signal@Gtk.ApplicationWindow::save-state] signal. There are also
[signal@Gtk.Application::restore-state] and
[signal@GtkApplication::save-state] signals, which can be used for global
state that is not connected to any window. GtkApplication automatically
saves state before app shutdown, and by default periodically auto-saves app
state (as configured by the [property@Gtk.Application:autosave-interval]
property). Applications can also call [method@Gtk.Application.save]
themselves at opportune times. # Inhibiting An application can block various
ways to end the session with the [method@Gtk.Application.inhibit] function.
Typical use cases for this kind of inhibiting are long-running,
uninterruptible operations, such as burning a CD or performing a disk backup.
The session manager may not honor the inhibitor, but it can be expected to
inform the user about the negative consequences of ending the session while
inhibitors are present. ## A simple application A simple
example
is available in the GTK source code repository ## See Also - Using
GtkApplication
Application (application_id = null, flags = null)
Creates a new application instance. When using
GtkApplication, it is not necessary to call [func@Gtk.init] manually. It is called as soon as the application gets registered as the primary instance. Concretely, [func@Gtk.init] is called in the default handler for theGApplication::startupsignal. Therefore,GtkApplicationsubclasses should always chain up in their [vfunc@GIO.Application.startup] handler before using any GTK API. Note that commandline arguments are not passed to [func@Gtk.init]. Ifapplication_idis notNULL, then it must be valid. See [func@Gio.Application.id_is_valid]. If no application ID is given then some features (most notably application uniqueness) will be disabled.
application_id is The application ID.flags is the application flags.toNativeHandle (Source)
Normalizes a constructor argument into a raw pointer carrier. Accepts a raw NativeHandle, a raw NativeBuffer returned from
fn.call(...), another generated wrapper exposinghandle(), or null. Returns null when the argument carries no pointer.
Source is the raw handle, raw buffer, wrapper, or null.A raw pointer carrier or null when no pointer is present.getLib ()
Returns the opened native library for this generated wrapper.
The opened native library.handle ()
Returns the wrapped NativeHandle.
The wrapped NativeHandle.isNull ()
Returns true when the wrapped handle is null.
A bool.describe ()
Returns a small string for debugging generated wrappers.
A string.asApplication ()
Wraps this handle as
Application.
A Application object.asActionGroup ()
Wraps this handle as
ActionGroup.
A ActionGroup object.asActionMap ()
Wraps this handle as
ActionMap.
A ActionMap object.connectSignal (string Name, CallbackObj)
Connects one generated callback wrapper to a named signal.
Name is the signal name.CallbackObj is the generated callback wrapper to connect.The connected handler id.disconnectSignalHandler (int HandlerId)
Disconnects one retained signal handler id.
HandlerId is the signal handler id to disconnect.None.setOnQueryend (callback Fn, UserData = null)
Emitted when the session manager is about to end the session. Applications can connect to this signal and call [method@Gtk.Application.inhibit] with [flags@Gtk.ApplicationInhibitFlags.logout] to delay the end of the session until state has been saved.
Fn is the Aussom callback.Fn is called with (Application Self).UserData is retained and passed through to the generated callback wrapper when provided.The connected handler id.setOnRestorestate (callback Fn, UserData = null)
Emitted when application global state is restored. The handler for this signal should do the opposite of what the corresponding handler for [signal@Gtk.Application::save-state] does.
Fn is the Aussom callback.Fn is called with (Application Self, string Reason, Variant State).UserData is retained and passed through to the generated callback wrapper when provided.The connected handler id.setOnRestorewindow (callback Fn, UserData = null)
Emitted when an application's per-window state is restored. In response to this signal, you should create a new application window, add it to
apply the provided @state, and present it. The application can use the @reason to determine how much of the state should be restored. You must be careful to be robust in the face of app upgrades and downgrades: the @state might have been created by a previous or occasionally even a future version of your app. Do not assume that a given key exists in the state. Apps must try to restore state saved by a previous version, but are free to discard state if it was written by a future version. GTK will remember which window the user was using most recently, and will emit this signal for that window first. Thus, if you decide that the provided @reason means that only one window should be restored, you can reliably ignore emissions if a window already exists Note that this signal is not emitted only during the app's initial launch. If all windows are closed but the app keeps running, the signal will be emitted the next time a new window is opened.Fn is the Aussom callback.Fn is called with (Application Self, string Reason, Variant State).UserData is retained and passed through to the generated callback wrapper when provided.The connected handler id.setOnSavestate (callback Fn, UserData = null)
Emitted when the application is saving global state. The handler for this signal should persist any global state of @application into @dict. See [signal@Gtk.Application::restore-state] for how to restore global state, and [signal@Gtk.ApplicationWindow::save-state] and [signal@Gtk.Application::restore-window] for handling per-window state.
Fn is the Aussom callback.Fn is called with (Application Self, VariantDict Dict).UserData is retained and passed through to the generated callback wrapper when provided.The connected handler id.setOnWindowadded (callback Fn, UserData = null)
Emitted when a window is added to an application. See [method@Gtk.Application.add_window].
Fn is the Aussom callback.Fn is called with (Application Self, Window Window).UserData is retained and passed through to the generated callback wrapper when provided.The connected handler id.setOnWindowremoved (callback Fn, UserData = null)
Emitted when a window is removed from an application. This can happen as a side-effect of the window being destroyed or explicitly through [method@Gtk.Application.remove_window].
Fn is the Aussom callback.Fn is called with (Application Self, Window Window).UserData is retained and passed through to the generated callback wrapper when provided.The connected handler id.getProperty (string Name)
Reads one generated property by name.
setProperty (string Name, Value)
Writes one generated property by name.
setAutosaveinterval (int Value)
The number of seconds between automatic state saves. Defaults to 15. A value of 0 will opt out of automatic state saving.
Value is the new property value.None.setMenubar (object Value)
The menu model to be used for the application's menu bar.
Value is the new property value.None.setRegistersession (bool Value)
Set this property to true to register with the session manager. This will make GTK track the session state (such as the [property@Gtk.Application:screensaver-active] property).
Value is the new property value.None.setSupportsave (bool Value)
Set this property to true if the application supports state saving and restoring.
Value is the new property value.None.add_window (object window)
Adds a window to the application. This call can only happen after the application has started; typically, you should add new application windows in response to the emission of the [signal@GIO.Application::activate] signal. This call is equivalent to setting the [property@Gtk.Window:application] property of the window to
Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it with [method@Gtk.Application.remove_window]. GTK will keep the application running as long as it has any windows.window is a window.None.forget ()
Forget state that has been previously saved and prevent further automatic state saving. In order to reenable state saving, call [method@Gtk.Application.save].
None.get_accels_for_action (string detailed_action_name)
Gets the accelerators that are currently associated with the given action.
detailed_action_name is a detailed action name, specifying an action and target to obtain accelerators for.get_actions_for_accel (string accel)
Returns the list of actions (possibly empty) that the accelerator maps to. Each item in the list is a detailed action name in the usual form. This might be useful to discover if an accel already exists in order to prevent installation of a conflicting accelerator (from an accelerator editor or a plugin system, for example). Note that having more than one action per accelerator may not be a bad thing and might make sense in cases where the actions never appear in the same context. In case there are no actions for a given accelerator, an empty array is returned.
NULLis never returned. It is a programmer error to pass an invalid accelerator string. If you are unsure, check it with [func@Gtk.accelerator_parse] first.
accel is an accelerator that can be parsed by [func@Gtk.accelerator_parse].get_active_window ()
Gets the “active” window for the application. The active window is the one that was most recently focused (within the application). This window may not have the focus at the moment if another application has it — this is just the most recently-focused window within this application.
get_menu_by_id (string id)
Gets a menu from automatically loaded resources. See the section on Automatic resources for more information.
id is the ID of the menu to look up.get_menubar ()
Returns the menu model for the menu bar of the application.
get_window_by_id (int id)
Returns the window with the given ID. The ID of a
GtkApplicationWindowcan be retrieved with [method@Gtk.ApplicationWindow.get_id].
id is an identifier number.get_windows ()
Gets a list of the window associated with the 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.
inhibit (object window, string flags, string reason)
Informs the session manager that certain types of actions should be inhibited. This is not guaranteed to work on all platforms and for all types of actions. Applications should invoke this method when they begin an operation that should not be interrupted, such as creating a CD or DVD. The types of actions that may be blocked are specified by the @flags parameter. When the application completes the operation it should call [method@Gtk.Application.uninhibit] to remove the inhibitor. Note that an application can have multiple inhibitors, and all of them must be individually removed. Inhibitors are also cleared when the application exits. Applications should not expect that they will always be able to block the action. In most cases, users will be given the option to force the action to take place. The @reason message should be short and to the point. If a window is given, the session manager may point the user to this window to find out more about why the action is inhibited. The cookie that is returned by this function should be used as an argument to [method@Gtk.Application.uninhibit] in order to remove the request.
window is a window.flags is what types of actions should be inhibited.reason is a short, human-readable string that explains why these operations are inhibited.list_action_descriptions ()
Lists the detailed action names which have associated accelerators. See [method@Gtk.Application.set_accels_for_action].
remove_window (object window)
Remove a window from the application. If the window belongs to the application then this call is equivalent to setting the [property@Gtk.Window:application] property of the window to
NULL. The application may stop running as a result of a call to this function, if the window was the last window of the application.
window is a window.None.save ()
Saves the state of application. See [method@Gtk.Application.forget] for a way to forget the state. If [property@Gtk.Application:register-session] is set,
GtkApplicationcalls this function automatically when the application is closed or the session ends.
None.set_accels_for_action (string detailed_action_name, list accels)
Sets zero or more keyboard accelerators that will trigger the given action. The first item in @accels will be the primary accelerator, which may be displayed in the UI. To remove all accelerators for an action, use an empty, zero-terminated array for @accels. For the
see [func@Gio.Action.parse_detailed_name] and [Gio.Action.print_detailed_name].detailed_action_name is a detailed action name, specifying an action and target to associate accelerators with.accels is a list of accelerators in the format understood by [func@Gtk.accelerator_parse].None.set_menubar (object menubar)
Sets or unsets the menubar for windows of the application. This is a menubar in the traditional sense. This can only be done in the primary instance of the application, after it has been registered. [vfunc@GIO.Application.startup] is a good place to call this. 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. Use the base
GActionMapinterface to add actions, to respond to the user selecting these menu items.
menubar is a menu model.None.uninhibit (int cookie)
Removes an inhibitor that has been previously established. See [method@Gtk.Application.inhibit]. Inhibitors are also cleared when the application exits.
cookie is a cookie that was returned by [method@Gtk.Application.inhibit].None.windows ()
Returns
get_windowsas an Aussom list of wrapper objects. This companion method materializes the full collection up front; useget_windows()when lazy or change-notify access is required.
An Aussom list of elements.[1140:14] static extends: object
Generated metadata helpers for Application class surfaces.
properties ()
Returns property metadata for
Application.
A list.signals ()
Returns signal metadata for
Application.
A list.[783:7] extends: object
Generated low-level callback wrapper for GIR callback restore-state.
ApplicationRestorestateCallback (callback Fn, UserData = null)
Creates one native callback wrapper. The wrapper owns a trampoline that converts native pointers into generated wrapper objects before invoking
Fn.
Fn is the Aussom callback implementation.UserData is retained and passed through to Fn on each invocation when provided.trampoline (nativeSelf, reason, state, nativeUserData)
Internal trampoline. Converts native pointer arguments into generated wrapper instances, then invokes the user's callback.
callback ()
Returns the wrapped NativeCallback.
handle ()
Returns the callback as a NativeHandle.
close ()
Closes the underlying NativeCallback.
isClosed ()
Returns true when the callback has been closed.
[998:7] extends: object
Generated low-level callback wrapper for GIR callback window-added.
ApplicationWindowaddedCallback (callback Fn, UserData = null)
Creates one native callback wrapper. The wrapper owns a trampoline that converts native pointers into generated wrapper objects before invoking
Fn.
Fn is the Aussom callback implementation.UserData is retained and passed through to Fn on each invocation when provided.trampoline (nativeSelf, window, nativeUserData)
Internal trampoline. Converts native pointer arguments into generated wrapper instances, then invokes the user's callback.
callback ()
Returns the wrapped NativeCallback.
handle ()
Returns the callback as a NativeHandle.
close ()
Closes the underlying NativeCallback.
isClosed ()
Returns true when the callback has been closed.
[1069:7] extends: object
Generated low-level callback wrapper for GIR callback window-removed.
ApplicationWindowremovedCallback (callback Fn, UserData = null)
Creates one native callback wrapper. The wrapper owns a trampoline that converts native pointers into generated wrapper objects before invoking
Fn.
Fn is the Aussom callback implementation.UserData is retained and passed through to Fn on each invocation when provided.trampoline (nativeSelf, window, nativeUserData)
Internal trampoline. Converts native pointer arguments into generated wrapper instances, then invokes the user's callback.
callback ()
Returns the wrapped NativeCallback.
handle ()
Returns the callback as a NativeHandle.
close ()
Closes the underlying NativeCallback.
isClosed ()
Returns true when the callback has been closed.
[713:7] extends: object
Generated low-level callback wrapper for GIR callback query-end.
ApplicationQueryendCallback (callback Fn, UserData = null)
Creates one native callback wrapper. The wrapper owns a trampoline that converts native pointers into generated wrapper objects before invoking
Fn.
Fn is the Aussom callback implementation.UserData is retained and passed through to Fn on each invocation when provided.trampoline (nativeSelf, nativeUserData)
Internal trampoline. Converts native pointer arguments into generated wrapper instances, then invokes the user's callback.
callback ()
Returns the wrapped NativeCallback.
handle ()
Returns the callback as a NativeHandle.
close ()
Closes the underlying NativeCallback.
isClosed ()
Returns true when the callback has been closed.
[855:7] extends: object
Generated low-level callback wrapper for GIR callback restore-window.
ApplicationRestorewindowCallback (callback Fn, UserData = null)
Creates one native callback wrapper. The wrapper owns a trampoline that converts native pointers into generated wrapper objects before invoking
Fn.
Fn is the Aussom callback implementation.UserData is retained and passed through to Fn on each invocation when provided.trampoline (nativeSelf, reason, state, nativeUserData)
Internal trampoline. Converts native pointer arguments into generated wrapper instances, then invokes the user's callback.
callback ()
Returns the wrapped NativeCallback.
handle ()
Returns the callback as a NativeHandle.
close ()
Closes the underlying NativeCallback.
isClosed ()
Returns true when the callback has been closed.
[927:7] extends: object
Generated low-level callback wrapper for GIR callback save-state.
ApplicationSavestateCallback (callback Fn, UserData = null)
Creates one native callback wrapper. The wrapper owns a trampoline that converts native pointers into generated wrapper objects before invoking
Fn.
Fn is the Aussom callback implementation.UserData is retained and passed through to Fn on each invocation when provided.trampoline (nativeSelf, dict, nativeUserData)
Internal trampoline. Converts native pointer arguments into generated wrapper instances, then invokes the user's callback.
callback ()
Returns the wrapped NativeCallback.
handle ()
Returns the callback as a NativeHandle.
close ()
Closes the underlying NativeCallback.
isClosed ()
Returns true when the callback has been closed.
