Struct Application 

pub struct Application { /* private fields */ }

Application 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, 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 GtkWindows, it is recommended to use it together with ApplicationWindow.

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 [ActionGroupExtManual::activate_action()][crate::gio::prelude::ActionGroupExtManual::activate_action()]. The same applies to actions associated with ApplicationWindow and to the “activate” and “open” gio::Application methods.

Automatic resources ## {automatic-resources}

Application will automatically load menus from the Builder resource located at “gtk/menus.ui”, relative to the application’s resource base path (see [ApplicationExtManual::set_resource_base_path()][crate::gio::prelude::ApplicationExtManual::set_resource_base_path()]). The menu with the ID “app-menu” is taken as the application’s app menu and the menu with the ID “menubar” is taken as the application’s menubar. Additional menus (most interesting submenus) can be named and accessed via GtkApplicationExt::menu_by_id() which allows for dynamic population of a part of the menu structure.

If the resources “gtk/menus-appmenu.ui” or “gtk/menus-traditional.ui” are present then these files will be used in preference, depending on the value of GtkApplicationExt::prefers_app_menu(). If the resource “gtk/menus-common.ui” is present it will be loaded as well. This is useful for storing items that are referenced from both “gtk/menus-appmenu.ui” and “gtk/menus-traditional.ui”.

It is also possible to provide the menus manually using GtkApplicationExt::set_app_menu() and GtkApplicationExt::set_menubar().

Application 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 IconThemeExt::add_resource_path() for more information.

If there is a resource located at “gtk/help-overlay.ui” which defines a ShortcutsWindow with ID “help_overlay” then GtkApplication associates an instance of this shortcuts window with each ApplicationWindow and sets up keyboard accelerators (Control-F1 and Control-?) to open it. To create a menu item that displays the shortcuts window, associate the item with the action win.show-help-overlay.

A simple application ## {gtkapplication}

A simple example

GtkApplication optionally registers with a session manager of the users session (if you set the register-session property) and offers various functionality related to the session life-cycle.

An application can block various ways to end the session with the GtkApplicationExt::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.

See Also ## {seealso}

HowDoI: Using GtkApplication, Getting Started with GTK+: Basics

Properties

active-window

Readable

app-menu

Readable | Writable

menubar

Readable | Writable

register-session

Set this property to true to register with the session manager.

Readable | Writable

screensaver-active

This property is true if GTK+ believes that the screensaver is currently active. GTK+ only tracks session state (including this) when register-session is set to true.

Tracking the screensaver state is supported on Linux.

Readable

Application

action-group

The group of actions that the application exports.

Writable

application-id

The unique identifier for the application.

Readable | Writable | Construct

flags

Flags specifying the behaviour of the application.

Readable | Writable

inactivity-timeout

Time (in milliseconds) to stay alive after becoming idle.

Readable | Writable

is-busy

Whether the application is currently marked as busy through ApplicationExtManual::mark_busy() or [ApplicationExtManual::bind_busy_property()][crate::gio::prelude::ApplicationExtManual::bind_busy_property()].

Readable

is-registered

Whether [methodGio.register] has been called.

Readable

is-remote

Whether this application instance is remote.

Readable

resource-base-path

The base resource path for the application.

Readable | Writable

version

The human-readable version number of the application.

Readable | Writable

Signals

query-end

Emitted when the session manager is about to end the session, only if register-session is true. Applications can connect to this signal and call GtkApplicationExt::inhibit() with ApplicationInhibitFlags::LOGOUT to delay the end of the session until state has been saved.

window-added

Emitted when a Window is added to application through GtkApplicationExt::add_window().

window-removed

Emitted when a Window is removed from application, either as a side-effect of being destroyed or explicitly through GtkApplicationExt::remove_window().

Application

activate

The ::activate signal is emitted on the primary instance when an activation occurs. See [ApplicationExtManual::activate()][crate::gio::prelude::ApplicationExtManual::activate()].

command-line

The ::command-line signal is emitted on the primary instance when a commandline is not handled locally. See ApplicationExtManual::run() and the GApplicationCommandLine documentation for more information.

handle-local-options

The ::handle-local-options signal is emitted on the local instance after the parsing of the commandline options has occurred.

You can add options to be recognised during commandline option parsing using [ApplicationExtManual::add_main_option_entries()][crate::gio::prelude::ApplicationExtManual::add_main_option_entries()] and [ApplicationExtManual::add_option_group()][crate::gio::prelude::ApplicationExtManual::add_option_group()].

Signal handlers can inspect options (along with values pointed to from the arg_data of an installed GOptionEntrys) in order to decide to perform certain actions, including direct local handling (which may be useful for options like –version).

In the event that the application is marked gio::ApplicationFlags::HANDLES_COMMAND_LINE the “normal processing” will send the options dictionary to the primary instance where it can be read with g_application_command_line_get_options_dict(). The signal handler can modify the dictionary before returning, and the modified dictionary will be sent.

In the event that gio::ApplicationFlags::HANDLES_COMMAND_LINE is not set, “normal processing” will treat the remaining uncollected command line arguments as filenames or URIs. If there are no arguments, the application is activated by [ApplicationExtManual::activate()][crate::gio::prelude::ApplicationExtManual::activate()]. One or more arguments results in a call to [ApplicationExtManual::open()][crate::gio::prelude::ApplicationExtManual::open()].

If you want to handle the local commandline arguments for yourself by converting them to calls to [ApplicationExtManual::open()][crate::gio::prelude::ApplicationExtManual::open()] or [ActionGroupExtManual::activate_action()][crate::gio::prelude::ActionGroupExtManual::activate_action()] then you must be sure to register the application first. You should probably not call [ApplicationExtManual::activate()][crate::gio::prelude::ApplicationExtManual::activate()] for yourself, however: just return -1 and allow the default handler to do it for you. This will ensure that the --gapplication-service switch works properly (i.e. no activation in that case).

Note that this signal is emitted from the default implementation of local_command_line(). If you override that function and don’t chain up then this signal will never be emitted.

You can override local_command_line() if you need more powerful capabilities than what is provided here, but this should not normally be required.

name-lost

The ::name-lost signal is emitted only on the registered primary instance when a new instance has taken over. This can only happen if the application is using the gio::ApplicationFlags::ALLOW_REPLACEMENT flag.

The default handler for this signal calls [ApplicationExtManual::quit()][crate::gio::prelude::ApplicationExtManual::quit()].

open

The ::open signal is emitted on the primary instance when there are files to open. See [ApplicationExtManual::open()][crate::gio::prelude::ApplicationExtManual::open()] for more information.

shutdown

The ::shutdown signal is emitted only on the registered primary instance immediately after the main loop terminates.

startup

The ::startup signal is emitted on the primary instance immediately after registration. See [ApplicationExtManual::register()][crate::gio::prelude::ApplicationExtManual::register()].

ActionGroup

action-added

Signals that a new action was just added to the group.

This signal is emitted after the action has been added and is now visible.

Detailed

action-enabled-changed

Signals that the enabled status of the named action has changed.

Detailed

action-removed

Signals that an action is just about to be removed from the group.

This signal is emitted before the action is removed, so the action is still visible and can be queried from the signal handler.

Detailed

action-state-changed

Signals that the state of the named action has changed.

Detailed

Implements

GtkApplicationExt, gio::prelude::ApplicationExt, [trait@glib::ObjectExt], gio::prelude::ActionGroupExt, gio::prelude::ActionMapExt, [gio::ApplicationExtManual][trait@crate::prelude::gio::ApplicationExtManual]

GLib type: GObject with reference counted clone semantics.

Implementations

impl Application

pub const NONE: Option<&'static Application> = None

pub fn builder() -> ApplicationBuilder

Creates a new builder-pattern struct instance to construct Application objects.

This method returns an instance of ApplicationBuilder which can be used to create Application objects.

impl Application

pub fn new(application_id: Option<&str>, flags: ApplicationFlags) -> Application

Trait Implementations

impl Clone for Application

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the object. Dropping the object will decrement it again.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Application

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Application

impl HasParamSpec for Application

type ParamSpec = ParamSpecObject

type SetValue = Application

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(&str) -> ParamSpecObjectBuilder<'_, Application>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Application

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Hashes the memory address of this object.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IsA<ActionGroup> for Application

impl IsA<ActionMap> for Application

impl IsA<Application> for Application

impl<T: GtkApplicationImpl> IsSubclassable<T> for Application

fn class_init(class: &mut Class<Self>)

Override the virtual methods of this class for the given subclass and do other class initialization.

fn instance_init(instance: &mut InitializingObject<T>)

Instance specific initialization.

impl Ord for Application

fn cmp(&self, other: &Self) -> Ordering

Comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl ParentClassIs for Application

type Parent = Application

impl<OT: ObjectType> PartialEq<OT> for Application

fn eq(&self, other: &OT) -> bool

Equality for two GObjects.

Two GObjects are equal if their memory addresses are equal.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<OT: ObjectType> PartialOrd<OT> for Application

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

Partial comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Application

fn static_type() -> Type

Returns the type identifier of Self.