## Executing Applications

Executing Applications — Execute preferred applications

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <exo/exo.h>

    gboolean            exo_execute_preferred_application   (const gchar *category,
                                                             const gchar *parameter,
                                                             const gchar *working_directory,
                                                             gchar **envp,
                                                             GError **error);
    gboolean            exo_execute_preferred_application_on_screen
                                                            (const gchar *category,
                                                             const gchar *parameter,
                                                             const gchar *working_directory,
                                                             gchar **envp,
                                                             GdkScreen *screen,
                                                             GError **error);
    gboolean            exo_execute_terminal_shell          (const gchar *command_line,
                                                             const gchar *working_directory,
                                                             gchar **envp,
                                                             GError **error);
    gboolean            exo_execute_terminal_shell_on_screen
                                                            (const gchar *command_line,
                                                             const gchar *working_directory,
                                                             gchar **envp,
                                                             GdkScreen *screen,
                                                             GError **error);

## Description

This module provides functions to execute certain kinds of applications, for which users can select their preferred ones. For example, whenever you need to run a command in a terminal emulator from within your application you should use `exo_execute_terminal_shell()` or `exo_execute_terminal_shell_on_screen()` to make sure you run the user's preferred terminal emulator.

On the other hand if you need to display an URL (i.e. you want to point the user to the website of your application), you should use `exo_url_show()` or `exo_url_show_on_screen()` from the exo-url module instead, as they will try to automatically determine the appropriate viewer for a given URL.

## Details

### exo_execute_preferred_application ()

    gboolean            exo_execute_preferred_application   (const gchar *category,
                                                             const gchar *parameter,
                                                             const gchar *working_directory,
                                                             gchar **envp,
                                                             GError **error);

Convenience wrapper to `exo_execute_preferred_application_on_screen()`, which runs the preferred application for `category` on the default GdkScreen.

Note that even if this method returns `TRUE` there's no warranty that the preferred application for `category` was run successfully, because of the way the helper framework is implemented. But you can be sure that if the execution fails at a later stage, the library will popup an error dialog to inform the user that the execution failed.

`category` : | the category of the preferred application to launch.
`parameter` : | additional parameter to pass to the preferred application (i.e. an URL to pass to the preferred browser) or `NULL` to pass no parameter.
`working_directory` : | path to the directory in which to execute the preferred application for `category`.
`envp` : | child's environment, or `NULL` to inherit parent's.
`error` : | return location for errors or `NULL`.
Returns : | `TRUE` on success, else `FALSE`.

Since 0.3.1.3

### exo_execute_preferred_application_on_screen ()

    gboolean            exo_execute_preferred_application_on_screen
                                                            (const gchar *category,
                                                             const gchar *parameter,
                                                             const gchar *working_directory,
                                                             gchar **envp,
                                                             GdkScreen *screen,
                                                             GError **error);

Launches the preferred application for the given `category` with the `parameter` on `screen` in the specified `working_directory`.

libexo currently supports the following categories: %"WebBrowser", %"MailReader" and %"TerminalEmulator". If you specify an invalid `category` here, the execution will fail at a later stage and the user will be presented with an error dialog.

Note that even if this method returns `TRUE` there's no warranty that the preferred application for `category` was run successfully, because of the way the helper framework is implemented. But you can be sure that if the execution fails at a later stage, the library will popup an error dialog to inform the user that the execution failed.

`category` : | the category of the preferred application to launch.
`parameter` : | additional parameter to pass to the preferred application (i.e. an URL to pass to the preferred browser) or `NULL` to pass no parameter.
`working_directory` : | path to the directory in which to execute the preferred application for `category`.
`envp` : | child's environment, or `NULL` to inherit parent's.
`screen` : | the GdkScreen on which to run the preferred application for `category`.
`error` : | return location for errors or `NULL`.
Returns : | `TRUE` on success, else `FALSE`.

Since 0.3.1.3

### exo_execute_terminal_shell ()

    gboolean            exo_execute_terminal_shell          (const gchar *command_line,
                                                             const gchar *working_directory,
                                                             gchar **envp,
                                                             GError **error);

Convenience wrapper to `exo_execute_terminal_shell_on_screen()`, which executes the `command_line` on the default GdkScreen.

Note that even if this method returns `TRUE` there's no warranty that the `command_line` was run successfully, because of the way the helper framework is implemented. But you can be sure that if the execution fails at a later stage, the library will popup an error dialog to inform the user that the execution failed.

`command_line` : | shell command line to execute.
`working_directory` : | path to the directory in which to execute `command_line` or `NULL` to use the current working directory.
`envp` : | child's environment, or `NULL` to inherit parent's.
`error` : | return location for errors or `NULL`.
Returns : | `TRUE` on success, else `FALSE`.

Since 0.3.1.3

### exo_execute_terminal_shell_on_screen ()

    gboolean            exo_execute_terminal_shell_on_screen
                                                            (const gchar *command_line,
                                                             const gchar *working_directory,
                                                             gchar **envp,
                                                             GdkScreen *screen,
                                                             GError **error);

Executes `command_line` in the default terminal emulator on the specified `screen`.

If no preferred terminal emulator was chosen by the user so far and no sane fallback could be located, the user will be presented with the preferred application chooser dialog, which prompts to choose a default terminal emulator, and the `command_line` will be run afterwards using the new default.

Note that even if this method returns `TRUE` there's no warranty that the `command_line` was run successfully, because of the way the helper framework is implemented. But you can be sure that if the execution fails at a later stage, the library will popup an error dialog to inform the user that the execution failed.

`command_line` : | shell command line to execute.
`working_directory` : | path to the directory in which to execute `command_line` or `NULL` to use the current working directory.
`envp` : | child's environment, or `NULL` to inherit parent's.
`screen` : | the GdkScreen on which to run the `command_line`.
`error` : | return location for errors or `NULL`.
Returns : | `TRUE` on success, else `FALSE`.

Since 0.3.1.3

## See Also

Opening URLs