Struct gtk4::Application

pub struct Application { /* private fields */ }

Application is a high-level API for writing applications.

It supports many aspects of writing a GTK application in a convenient fashion, without enforcing a one-size-fits-all model.

Currently, Application 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 Application works fine with plain Windows, it is recommended to use it together with ApplicationWindow.

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 “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.

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 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 IconTheme::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 Application associates an instance of this shortcuts window with each 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.

A simple application

A simple example is available in the GTK source code repository

Application 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

HowDoI: Using GtkApplication, Getting Started with GTK: Basics

Properties

active-window

The currently focused window of the application.

Readable

menubar

The GMenuModel to be used for the application’s menu bar.

Readable | Writeable

register-session

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

This will make GTK track the session state (such as the screensaver-active property).

Readable | Writeable

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 currently only supported on Linux.

Readable

Application

action-group

The group of actions that the application exports.

Writeable

application-id

The unique identifier for the application.

Readable | Writeable | Construct

flags

Flags specifying the behaviour of the application.

Readable | Writeable

inactivity-timeout

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

Readable | Writeable

is-busy

Whether the application is currently marked as busy through g_application_mark_busy() or g_application_bind_busy_property().

Readable

is-registered

Whether [ApplicationExtManual::register()][crate::gio::prelude::ApplicationExtManual::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 | Writeable

version

The human-readable version number of the application.

Readable | Writeable

Signals

query-end

Emitted when the session manager is about to end the session.

This signal is only emitted if register-session is TRUE. Applications can connect to this signal and call GtkApplicationExt::inhibit() with GTK_APPLICATION_INHIBIT_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.

This can happen as a side-effect of the window being destroyed or explicitly through GtkApplicationExt::remove_window().

Application

activate

The ::activate signal is emitted on the primary instance when an activation occurs. See g_application_activate().

command-line

The ::command-line signal is emitted on the primary instance when a commandline is not handled locally. See g_application_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 g_application_add_main_option_entries() and g_application_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 g_application_activate(). One or more arguments results in a call to g_application_open().

If you want to handle the local commandline arguments for yourself by converting them to calls to g_application_open() or g_action_group_activate_action() then you must be sure to register the application first. You should probably not call g_application_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 g_application_quit().

open

The ::open signal is emitted on the primary instance when there are files to open. See g_application_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 g_application_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

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: impl IntoOptionalGStr, flags: ApplicationFlags ) -> Self

Trait Implementations

impl Clone for Application

fn clone(&self) -> Self

Returns a copy of the value.

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 Default for Application

fn default() -> Self

Returns the “default value” for a type.

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,

Feeds this value into the given Hasher.

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

This method returns an Ordering between self and other.

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 + PartialOrd,

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

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

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method 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.

impl Eq for Application

impl IsA<ActionGroup> for Application

impl IsA<ActionMap> for Application

impl IsA<Application> for Application