Trait ApplicationExtManual

pub trait ApplicationExtManual: IsA<Application> {
    // Provided methods
    fn run(&self) -> ExitCode { ... }
    fn run_with_args<S: AsRef<str>>(&self, args: &[S]) -> ExitCode { ... }
    fn connect_open<F: Fn(&Self, &[File], &str) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }
    fn connect_command_line<F: Fn(&Self, &ApplicationCommandLine) -> ExitCode + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }
    fn connect_handle_local_options<F: Fn(&Self, &VariantDict) -> ControlFlow<ExitCode> + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }
    fn hold(&self) -> ApplicationHoldGuard { ... }
    fn mark_busy(&self) -> ApplicationBusyGuard { ... }
}

Provided Methods

fn run(&self) -> ExitCode

Runs the application.

This function is intended to be run from main() and its return value is intended to be returned by main(). Although you are expected to pass the @argc, @argv parameters from main() to this function, it is possible to pass None if @argv is not available or commandline handling is not required. Note that on Windows, @argc and @argv are ignored, and g_win32_get_command_line() is called internally (for proper support of Unicode commandline arguments).

#GApplication will attempt to parse the commandline arguments. You can add commandline flags to the list of recognised options by way of g_application_add_main_option_entries(). After this, the #GApplication::handle-local-options signal is emitted, from which the application can inspect the values of its #GOptionEntrys.

#GApplication::handle-local-options is a good place to handle options such as --version, where an immediate reply from the local process is desired (instead of communicating with an already-running instance). A #GApplication::handle-local-options handler can stop further processing by returning a non-negative value, which then becomes the exit status of the process.

What happens next depends on the flags: if ApplicationFlags::HANDLES_COMMAND_LINE was specified then the remaining commandline arguments are sent to the primary instance, where a #GApplication::command-line signal is emitted. Otherwise, the remaining commandline arguments are assumed to be a list of files. If there are no files listed, the application is activated via the #GApplication::activate signal. If there are one or more files, and ApplicationFlags::HANDLES_OPEN was specified then the files are opened via the #GApplication::open signal.

If you are interested in doing more complicated local handling of the commandline then you should implement your own #GApplication subclass and override local_command_line(). In this case, you most likely want to return true from your local_command_line() implementation to suppress the default handling. See [gapplication-example-cmdline2.c][https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c] for an example.

If, after the above is done, the use count of the application is zero then the exit status is returned immediately. If the use count is non-zero then the default main context is iterated until the use count falls to zero, at which point 0 is returned.

If the ApplicationFlags::IS_SERVICE flag is set, then the service will run for as much as 10 seconds with a use count of zero while waiting for the message that caused the activation to arrive. After that, if the use count falls to zero the application will exit immediately, except in the case that g_application_set_inactivity_timeout() is in use.

This function sets the prgname (g_set_prgname()), if not already set, to the basename of argv[0].

Much like g_main_loop_run(), this function will acquire the main context for the duration that the application is running.

Since 2.40, applications that are not explicitly flagged as services or launchers (ie: neither ApplicationFlags::IS_SERVICE or ApplicationFlags::IS_LAUNCHER are given as flags) will check (from the default handler for local_command_line) if “–gapplication-service” was given in the command line. If this flag is present then normal commandline processing is interrupted and the ApplicationFlags::IS_SERVICE flag is set. This provides a “compromise” solution whereby running an application directly from the commandline will invoke it in the normal way (which can be useful for debugging) while still allowing applications to be D-Bus activated in service mode. The D-Bus service file should invoke the executable with “–gapplication-service” as the sole commandline argument. This approach is suitable for use by most graphical applications but should not be used from applications like editors that need precise control over when processes invoked via the commandline will exit and what their exit status will be.

argv

the argv from main(), or [`None`]

Returns

the exit status

fn run_with_args<S: AsRef<str>>(&self, args: &[S]) -> ExitCode

fn connect_open<F: Fn(&Self, &[File], &str) + 'static>( &self, f: F, ) -> SignalHandlerId

The ::open signal is emitted on the primary instance when there are files to open. See g_application_open() for more information.

files

an array of #GFiles

hint

a hint provided by the calling instance

fn connect_command_line<F: Fn(&Self, &ApplicationCommandLine) -> ExitCode + 'static>( &self, f: F, ) -> SignalHandlerId

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.

command_line

a #GApplicationCommandLine representing the passed commandline

Returns

An integer that is set as the exit status for the calling process. See g_application_command_line_set_exit_status().

fn connect_handle_local_options<F: Fn(&Self, &VariantDict) -> ControlFlow<ExitCode> + '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 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 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.

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.

fn hold(&self) -> ApplicationHoldGuard

Increases the use count of @self.

Use this function to indicate that the application has a reason to continue to run. For example, g_application_hold() is called by GTK when a toplevel window is on the screen.

To cancel the hold, call g_application_release().

fn mark_busy(&self) -> ApplicationBusyGuard

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 g_application_unmark_busy().

The application must be registered before calling this function.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<O: IsA<Application>> ApplicationExtManual for O