Trait gio::prelude::ApplicationExt
source · pub trait ApplicationExt: 'static {
Show 45 methods
// Required methods
fn activate(&self);
fn add_main_option(
&self,
long_name: &str,
short_name: Char,
flags: OptionFlags,
arg: OptionArg,
description: &str,
arg_description: Option<&str>
);
fn bind_busy_property(&self, object: &impl IsA<Object>, property: &str);
fn application_id(&self) -> Option<GString>;
fn dbus_connection(&self) -> Option<DBusConnection>;
fn dbus_object_path(&self) -> Option<GString>;
fn flags(&self) -> ApplicationFlags;
fn inactivity_timeout(&self) -> u32;
fn is_busy(&self) -> bool;
fn is_registered(&self) -> bool;
fn is_remote(&self) -> bool;
fn resource_base_path(&self) -> Option<GString>;
fn hold(&self);
fn mark_busy(&self);
fn open(&self, files: &[File], hint: &str);
fn quit(&self);
fn register(
&self,
cancellable: Option<&impl IsA<Cancellable>>
) -> Result<(), Error>;
fn release(&self);
fn send_notification(&self, id: Option<&str>, notification: &Notification);
fn set_application_id(&self, application_id: Option<&str>);
fn set_default(&self);
fn set_flags(&self, flags: ApplicationFlags);
fn set_inactivity_timeout(&self, inactivity_timeout: u32);
fn set_option_context_description(&self, description: Option<&str>);
fn set_option_context_parameter_string(
&self,
parameter_string: Option<&str>
);
fn set_option_context_summary(&self, summary: Option<&str>);
fn set_resource_base_path(&self, resource_path: Option<&str>);
fn unbind_busy_property(&self, object: &impl IsA<Object>, property: &str);
fn unmark_busy(&self);
fn withdraw_notification(&self, id: &str);
fn set_action_group<P: IsA<ActionGroup>>(&self, action_group: Option<&P>);
fn connect_activate<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId;
fn connect_command_line<F: Fn(&Self, &ApplicationCommandLine) -> i32 + 'static>(
&self,
f: F
) -> SignalHandlerId;
fn connect_handle_local_options<F: Fn(&Self, &VariantDict) -> i32 + 'static>(
&self,
f: F
) -> SignalHandlerId;
fn connect_name_lost<F: Fn(&Self) -> bool + 'static>(
&self,
f: F
) -> SignalHandlerId;
fn connect_shutdown<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId;
fn connect_startup<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId;
fn connect_action_group_notify<F: Fn(&Self) + 'static>(
&self,
f: F
) -> SignalHandlerId;
fn connect_application_id_notify<F: Fn(&Self) + 'static>(
&self,
f: F
) -> SignalHandlerId;
fn connect_flags_notify<F: Fn(&Self) + 'static>(
&self,
f: F
) -> SignalHandlerId;
fn connect_inactivity_timeout_notify<F: Fn(&Self) + 'static>(
&self,
f: F
) -> SignalHandlerId;
fn connect_is_busy_notify<F: Fn(&Self) + 'static>(
&self,
f: F
) -> SignalHandlerId;
fn connect_is_registered_notify<F: Fn(&Self) + 'static>(
&self,
f: F
) -> SignalHandlerId;
fn connect_is_remote_notify<F: Fn(&Self) + 'static>(
&self,
f: F
) -> SignalHandlerId;
fn connect_resource_base_path_notify<F: Fn(&Self) + 'static>(
&self,
f: F
) -> SignalHandlerId;
}
Expand description
Required Methods§
sourcefn activate(&self)
fn activate(&self)
Activates the application.
In essence, this results in the signal::Application::activate
signal being
emitted in the primary instance.
The application must be registered before calling this function.
sourcefn add_main_option(
&self,
long_name: &str,
short_name: Char,
flags: OptionFlags,
arg: OptionArg,
description: &str,
arg_description: Option<&str>
)
fn add_main_option( &self, long_name: &str, short_name: Char, flags: OptionFlags, arg: OptionArg, description: &str, arg_description: Option<&str> )
Add an option to be handled by self
.
Calling this function is the equivalent of calling
g_application_add_main_option_entries()
with a single GOptionEntry
that has its arg_data member set to None
.
The parsed arguments will be packed into a glib::VariantDict
which
is passed to signal::Application::handle-local-options
. If
ApplicationFlags::HANDLES_COMMAND_LINE
is set, then it will also
be sent to the primary instance. See
g_application_add_main_option_entries()
for more details.
See GOptionEntry
for more documentation of the arguments.
long_name
the long name of an option used to specify it in a commandline
short_name
the short name of an option
flags
flags from glib::OptionFlags
arg
the type of the option, as a glib::OptionArg
description
the description for the option in --help
output
arg_description
the placeholder to use for the extra argument
parsed by the option in --help
output
sourcefn bind_busy_property(&self, object: &impl IsA<Object>, property: &str)
fn bind_busy_property(&self, object: &impl IsA<Object>, property: &str)
Marks self
as busy (see mark_busy()
) while
property
on object
is true
.
The binding holds a reference to self
while it is active, but
not to object
. Instead, the binding is destroyed when object
is
finalized.
object
property
the name of a boolean property of object
sourcefn application_id(&self) -> Option<GString>
fn application_id(&self) -> Option<GString>
sourcefn dbus_connection(&self) -> Option<DBusConnection>
fn dbus_connection(&self) -> Option<DBusConnection>
Gets the DBusConnection
being used by the application, or None
.
If Application
is using its D-Bus backend then this function will
return the DBusConnection
being used for uniqueness and
communication with the desktop environment and other instances of the
application.
If Application
is not using D-Bus then this function will return
None
. This includes the situation where the D-Bus backend would
normally be in use but we were unable to connect to the bus.
This function must not be called before the application has been
registered. See is_registered()
.
Returns
a DBusConnection
, or None
sourcefn dbus_object_path(&self) -> Option<GString>
fn dbus_object_path(&self) -> Option<GString>
Gets the D-Bus object path being used by the application, or None
.
If Application
is using its D-Bus backend then this function will
return the D-Bus object path that Application
is using. If the
application is the primary instance then there is an object published
at this path. If the application is not the primary instance then
the result of this function is undefined.
If Application
is not using D-Bus then this function will return
None
. This includes the situation where the D-Bus backend would
normally be in use but we were unable to connect to the bus.
This function must not be called before the application has been
registered. See is_registered()
.
Returns
the object path, or None
sourcefn flags(&self) -> ApplicationFlags
fn flags(&self) -> ApplicationFlags
sourcefn inactivity_timeout(&self) -> u32
fn inactivity_timeout(&self) -> u32
sourcefn is_busy(&self) -> bool
fn is_busy(&self) -> bool
Gets the application’s current busy state, as set through
mark_busy()
or bind_busy_property()
.
Returns
true
if self
is currently marked as busy
sourcefn is_registered(&self) -> bool
fn is_registered(&self) -> bool
Checks if self
is registered.
An application is registered if register()
has been
successfully called.
Returns
true
if self
is registered
sourcefn is_remote(&self) -> bool
fn is_remote(&self) -> bool
Checks if self
is remote.
If self
is remote then it means that another instance of
application already exists (the ‘primary’ instance). Calls to
perform actions on self
will result in the actions being
performed by the primary instance.
The value of this property cannot be accessed before
register()
has been called. See
is_registered()
.
Returns
true
if self
is remote
sourcefn resource_base_path(&self) -> Option<GString>
fn resource_base_path(&self) -> Option<GString>
Gets the resource base path of self
.
See set_resource_base_path()
for more information.
Returns
the base resource path, if one is set
sourcefn mark_busy(&self)
fn mark_busy(&self)
Increases the busy count of self
.
Use this function to indicate that the application is busy, for instance while a long running operation is pending.
The busy state will be exposed to other processes, so a session shell will use that information to indicate the state to the user (e.g. with a spinner).
To cancel the busy indication, use unmark_busy()
.
The application must be registered before calling this function.
sourcefn open(&self, files: &[File], hint: &str)
fn open(&self, files: &[File], hint: &str)
Opens the given files.
In essence, this results in the signal::Application::open
signal being emitted
in the primary instance.
n_files
must be greater than zero.
hint
is simply passed through to the ::open signal. It is
intended to be used by applications that have multiple modes for
opening files (eg: “view” vs “edit”, etc). Unless you have a need
for this functionality, you should use “”.
The application must be registered before calling this function
and it must have the ApplicationFlags::HANDLES_OPEN
flag set.
files
an array of GFiles
to open
hint
a hint (or “”), but never None
sourcefn quit(&self)
fn quit(&self)
Immediately quits the application.
Upon return to the mainloop, ApplicationExtManual::run()
will return,
calling only the ‘shutdown’ function before doing so.
The hold count is ignored.
Take care if your code has called hold()
on the application and
is therefore still expecting it to exist.
(Note that you may have called hold()
indirectly, for example
through gtk_application_add_window()
.)
The result of calling ApplicationExtManual::run()
again after it returns is
unspecified.
sourcefn register(
&self,
cancellable: Option<&impl IsA<Cancellable>>
) -> Result<(), Error>
fn register( &self, cancellable: Option<&impl IsA<Cancellable>> ) -> Result<(), Error>
Attempts registration of the application.
This is the point at which the application discovers if it is the primary instance or merely acting as a remote for an already-existing primary instance. This is implemented by attempting to acquire the application identifier as a unique bus name on the session bus using GDBus.
If there is no application ID or if ApplicationFlags::NON_UNIQUE
was
given, then this process will always become the primary instance.
Due to the internal architecture of GDBus, method calls can be dispatched at any time (even if a main loop is not running). For this reason, you must ensure that any object paths that you wish to register are registered before calling this function.
If the application has already been registered then true
is
returned with no work performed.
The signal::Application::startup
signal is emitted if registration succeeds
and self
is the primary instance (including the non-unique
case).
In the event of an error (such as cancellable
being cancelled, or a
failure to connect to the session bus), false
is returned and error
is set appropriately.
Note: the return value of this function is not an indicator that this
instance is or is not the primary instance of the application. See
is_remote()
for that.
cancellable
a Cancellable
, or None
Returns
true
if registration succeeded
sourcefn release(&self)
fn release(&self)
Decrease the use count of self
.
When the use count reaches zero, the application will stop running.
Never call this function except to cancel the effect of a previous
call to hold()
.
sourcefn send_notification(&self, id: Option<&str>, notification: &Notification)
fn send_notification(&self, id: Option<&str>, notification: &Notification)
Sends a notification on behalf of self
to the desktop shell.
There is no guarantee that the notification is displayed immediately,
or even at all.
Notifications may persist after the application exits. It will be D-Bus-activated when the notification or one of its actions is activated.
Modifying notification
after this call has no effect. However, the
object can be reused for a later call to this function.
id
may be any string that uniquely identifies the event for the
application. It does not need to be in any special format. For
example, “new-message” might be appropriate for a notification about
new messages.
If a previous notification was sent with the same id
, it will be
replaced with notification
and shown again as if it was a new
notification. This works even for notifications sent from a previous
execution of the application, as long as id
is the same string.
id
may be None
, but it is impossible to replace or withdraw
notifications without an id.
If notification
is no longer relevant, it can be withdrawn with
withdraw_notification()
.
id
id of the notification, or None
notification
the Notification
to send
sourcefn set_application_id(&self, application_id: Option<&str>)
fn set_application_id(&self, application_id: Option<&str>)
Sets the unique identifier for self
.
The application id can only be modified if self
has not yet
been registered.
If non-None
, the application id must be valid. See
Application::id_is_valid()
.
application_id
the identifier for self
sourcefn set_default(&self)
fn set_default(&self)
Sets or unsets the default application for the process, as returned
by Application::default()
.
This function does not take its own reference on self
. If
self
is destroyed then the default application will revert
back to None
.
sourcefn set_flags(&self, flags: ApplicationFlags)
fn set_flags(&self, flags: ApplicationFlags)
Sets the flags for self
.
The flags can only be modified if self
has not yet been
registered.
See ApplicationFlags
.
flags
the flags for self
sourcefn set_inactivity_timeout(&self, inactivity_timeout: u32)
fn set_inactivity_timeout(&self, inactivity_timeout: u32)
Sets the current inactivity timeout for the application.
This is the amount of time (in milliseconds) after the last call to
release()
before the application stops running.
This call has no side effects of its own. The value set here is only
used for next time release()
drops the use count to
zero. Any timeouts currently in progress are not impacted.
inactivity_timeout
the timeout, in milliseconds
sourcefn set_option_context_description(&self, description: Option<&str>)
fn set_option_context_description(&self, description: Option<&str>)
v2_56
only.Adds a description to the self
option context.
See g_option_context_set_description()
for more information.
description
a string to be shown in --help
output
after the list of options, or None
sourcefn set_option_context_parameter_string(&self, parameter_string: Option<&str>)
fn set_option_context_parameter_string(&self, parameter_string: Option<&str>)
v2_56
only.Sets the parameter string to be used by the commandline handling of self
.
This function registers the argument to be passed to g_option_context_new()
when the internal GOptionContext
of self
is created.
See g_option_context_new()
for more information about parameter_string
.
parameter_string
a string which is displayed
in the first line of --help
output, after the usage summary programname [OPTION...]
.
sourcefn set_option_context_summary(&self, summary: Option<&str>)
fn set_option_context_summary(&self, summary: Option<&str>)
v2_56
only.sourcefn set_resource_base_path(&self, resource_path: Option<&str>)
fn set_resource_base_path(&self, resource_path: Option<&str>)
Sets (or unsets) the base resource path of self
.
The path is used to automatically load various [application resources][gresource] such as menu layouts and action descriptions. The various types of resources will be found at fixed names relative to the given base path.
By default, the resource base path is determined from the application
ID by prefixing ‘/’ and replacing each ‘.’ with ‘/’. This is done at
the time that the Application
object is constructed. Changes to
the application ID after that point will not have an impact on the
resource base path.
As an example, if the application has an ID of “org.example.app” then
the default resource base path will be “/org/example/app”. If this
is a GtkApplication
(and you have not manually changed the path)
then Gtk will then search for the menus of the application at
“/org/example/app/gtk/menus.ui”.
See Resource
for more information about adding resources to your
application.
You can disable automatic resource loading functionality by setting
the path to None
.
Changing the resource base path once the application is running is
not recommended. The point at which the resource path is consulted
for forming paths for various purposes is unspecified. When writing
a sub-class of Application
you should either set the
property::Application::resource-base-path
property at construction time, or call
this function during the instance initialization. Alternatively, you
can call this function in the GApplicationClass.startup
virtual function,
before chaining up to the parent implementation.
resource_path
the resource path to use
sourcefn unbind_busy_property(&self, object: &impl IsA<Object>, property: &str)
fn unbind_busy_property(&self, object: &impl IsA<Object>, property: &str)
Destroys a binding between property
and the busy state of
self
that was previously created with
bind_busy_property()
.
object
property
the name of a boolean property of object
sourcefn unmark_busy(&self)
fn unmark_busy(&self)
Decreases the busy count of self
.
When the busy count reaches zero, the new state will be propagated to other processes.
This function must only be called to cancel the effect of a previous
call to mark_busy()
.
sourcefn withdraw_notification(&self, id: &str)
fn withdraw_notification(&self, id: &str)
Withdraws a notification that was sent with
send_notification()
.
This call does nothing if a notification with id
doesn’t exist or
the notification was never sent.
This function works even for notifications sent in previous
executions of this application, as long id
is the same as it was for
the sent notification.
Note that notifications are dismissed when the user clicks on one of the buttons in a notification or triggers its default action, so there is no need to explicitly withdraw the notification in that case.
id
id of a previously sent notification
fn set_action_group<P: IsA<ActionGroup>>(&self, action_group: Option<&P>)
sourcefn connect_activate<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId
fn connect_activate<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId
The ::activate signal is emitted on the primary instance when an
activation occurs. See activate()
.
sourcefn connect_command_line<F: Fn(&Self, &ApplicationCommandLine) -> i32 + 'static>(
&self,
f: F
) -> SignalHandlerId
fn connect_command_line<F: Fn(&Self, &ApplicationCommandLine) -> i32 + 'static>( &self, f: F ) -> SignalHandlerId
The ::command-line signal is emitted on the primary instance when
a commandline is not handled locally. See ApplicationExtManual::run()
and
the ApplicationCommandLine
documentation for more information.
command_line
a ApplicationCommandLine
representing the
passed commandline
Returns
An integer that is set as the exit status for the calling
process. See ApplicationCommandLineExt::set_exit_status()
.
sourcefn connect_handle_local_options<F: Fn(&Self, &VariantDict) -> i32 + 'static>(
&self,
f: F
) -> SignalHandlerId
fn connect_handle_local_options<F: Fn(&Self, &VariantDict) -> i32 + 'static>( &self, f: F ) -> SignalHandlerId
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
ApplicationFlags::HANDLES_COMMAND_LINE
the “normal processing” will
send the options
dictionary to the primary instance where it can be
read with ApplicationCommandLineExt::options_dict()
. The signal
handler can modify the dictionary before returning, and the
modified dictionary will be sent.
In the event that 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 activate()
. One or
more arguments results in a call to open()
.
If you want to handle the local commandline arguments for yourself
by converting them to calls to open()
or
ActionGroupExt::activate_action()
then you must be sure to register
the application first. You should probably not call
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.
options
the options dictionary
Returns
an exit code. If you have handled your options and want to exit the process, return a non-negative option, 0 for success, and a positive value for failure. To continue, return -1 to let the default option processing continue.
sourcefn connect_name_lost<F: Fn(&Self) -> bool + 'static>(
&self,
f: F
) -> SignalHandlerId
fn connect_name_lost<F: Fn(&Self) -> bool + 'static>( &self, f: F ) -> SignalHandlerId
v2_60
only.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 ApplicationFlags::ALLOW_REPLACEMENT
flag.
The default handler for this signal calls quit()
.
Returns
true
if the signal has been handled
sourcefn connect_shutdown<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId
fn connect_shutdown<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId
The ::shutdown signal is emitted only on the registered primary instance immediately after the main loop terminates.
sourcefn connect_startup<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId
fn connect_startup<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId
The ::startup signal is emitted on the primary instance immediately
after registration. See register()
.