EShell

## EShell EShell — the backbone of Evolution |

## Synopsis

    #include <shell/e-shell.h>

    struct              EShell;
    EShell *	           e_shell_get_default                 (void);
    void                e_shell_load_modules                (EShell *shell);
    GList *		           e_shell_get_shell_backends          (EShell *shell);
    const gchar *	      e_shell_get_canonical_name          (EShell *shell,
                                                             const gchar *name);
    EShellBackend *	    e_shell_get_backend_by_name         (EShell *shell,
                                                             const gchar *name);
    EShellBackend *	    e_shell_get_backend_by_scheme       (EShell *shell,
                                                             const gchar *scheme);
    EShellSettings *    e_shell_get_shell_settings          (EShell *shell);
    GConfClient *	      e_shell_get_gconf_client            (EShell *shell);
    GtkWidget *	        e_shell_create_shell_window         (EShell *shell,
                                                             const gchar *view_name);
    guint               e_shell_handle_uris                 (EShell *shell,
                                                             const gchar * const *uris,
                                                             gboolean do_import);
    void                e_shell_submit_alert                (EShell *shell,
                                                             EAlert *alert);
    void                e_shell_watch_window                (EShell *shell,
                                                             GtkWindow *window);
    GList *		           e_shell_get_watched_windows         (EShell *shell);
    GtkWindow *         e_shell_get_active_window           (EShell *shell);
    gboolean            e_shell_get_meego_mode              (EShell *shell);
    gboolean            e_shell_get_express_mode            (EShell *shell);
    gboolean            e_shell_get_small_screen_mode       (EShell *shell);
    const gchar *	      e_shell_get_module_directory        (EShell *shell);
    gboolean            e_shell_get_network_available       (EShell *shell);
    void                e_shell_set_network_available       (EShell *shell,
                                                             gboolean network_available);
    void                e_shell_lock_network_available      (EShell *shell);
    gboolean            e_shell_get_online                  (EShell *shell);
    void                e_shell_set_online                  (EShell *shell,
                                                             gboolean online);
    GtkWidget *	        e_shell_get_preferences_window      (EShell *shell);
    void                e_shell_event                       (EShell *shell,
                                                             const gchar *event_name,
                                                             gpointer event_data);
    enum                EShellQuitReason;
    gboolean            e_shell_quit                        (EShell *shell,
                                                             EShellQuitReason reason);
    void                e_shell_cancel_quit                 (EShell *shell);
    void                e_shell_adapt_window_size           (EShell *shell,
                                                             GtkWindow *window);
    void                e_shell_set_startup_view            (EShell *shell,
                                                             const gchar *view);
    const gchar *	      e_shell_get_startup_view            (EShell *shell);
    #define             E_SHELL_MIGRATE_ERROR
    enum                EShellMigrateError;
    gboolean            e_shell_migrate_attempt             (EShell *shell);
    void                e_shell_detect_meego                (gboolean *is_meego,
                                                             gboolean *small_screen);

## Object Hierarchy

      GObject
       +----GApplication
             +----GtkApplication
                   +----EShell

## Implemented Interfaces

EShell implements GActionGroup, GInitable and EExtensible.

## Properties

      "express-mode"             gboolean              : Read / Write / Construct Only
      "geometry"                 gchar*                : Write / Construct Only
      "meego-mode"               gboolean              : Read / Write / Construct Only
      "module-directory"         gchar*                : Read / Write / Construct Only
      "network-available"        gboolean              : Read / Write / Construct
      "online"                   gboolean              : Read / Write / Construct
      "shell-settings"           EShellSettings*       : Read
      "small-screen-mode"        gboolean              : Read / Write / Construct Only

## Signals

      "event"                                          : Action
      "handle-uri"                                     : Action
      "prepare-for-offline"                            : Run First
      "prepare-for-online"                             : Run First
      "prepare-for-quit"                               : Run First
      "quit-requested"                                 : Run First
      "window-created"                                 : Run Last
      "window-destroyed"                               : Run Last

## Description

## Details

### struct EShell

    struct EShell;

Contains only private data that should be read and manipulated using the functions below.

### e_shell_get_default ()

    EShell *	           e_shell_get_default                 (void);

Returns the EShell created by ``main()``.

Try to obtain the EShell from elsewhere if you can. This function is intended as a temporary workaround for when that proves difficult.

Returns : | the EShell singleton

### e_shell_load_modules ()

    void                e_shell_load_modules                (EShell *shell);

Loads all installed modules and performs some internal bookkeeping. This function should be called after creating the EShell instance but before initiating migration or starting the main loop.

`shell` : | an EShell

### e_shell_get_shell_backends ()

    GList *		           e_shell_get_shell_backends          (EShell *shell);

Returns a list of loaded EShellBackend instances. The list is owned by `shell` and should not be modified or freed.

`shell` : | an EShell
Returns : | a list of loaded EShellBackend instances

### e_shell_get_canonical_name ()

    const gchar *	      e_shell_get_canonical_name          (EShell *shell,
                                                             const gchar *name);

Returns the canonical name for the EShellBackend whose name or alias is `name`.

`shell` : | an EShell
`name` : | the name or alias of an EShellBackend
Returns : | the canonical EShellBackend name

### e_shell_get_backend_by_name ()

    EShellBackend *	    e_shell_get_backend_by_name         (EShell *shell,
                                                             const gchar *name);

Returns the corresponding EShellBackend for the given name or alias, or `NULL` if `name` is not recognized.

`shell` : | an EShell
`name` : | the name or alias of an EShellBackend
Returns : | the EShellBackend named `name`, or `NULL`

### e_shell_get_backend_by_scheme ()

    EShellBackend *	    e_shell_get_backend_by_scheme       (EShell *shell,
                                                             const gchar *scheme);

Returns the EShellBackend that implements the given URI scheme, or `NULL` if `scheme` is not recognized.

`shell` : | an EShell
`scheme` : | a URI scheme
Returns : | the EShellBackend that implements `scheme`, or `NULL`

### e_shell_get_shell_settings ()

    EShellSettings *    e_shell_get_shell_settings          (EShell *shell);

Returns the EShellSettings instance for `shell`.

`shell` : | an EShell
Returns : | the EShellSettings instance for `shell`

### e_shell_get_gconf_client ()

    GConfClient *	      e_shell_get_gconf_client            (EShell *shell);

Returns the default GConfClient. This function is purely for convenience. The `shell` owns the reference so you don't have to.

`shell` : | an EShell
Returns : | the default GConfClient

### e_shell_create_shell_window ()

    GtkWidget *	        e_shell_create_shell_window         (EShell *shell,
                                                             const gchar *view_name);

Creates a new EShellWindow and emits the "window-created" signal. Use this function instead of `e_shell_window_new()` so that `shell` can track the window.

`shell` : | an EShell
`view_name` : | name of the initial shell view, or `NULL`
Returns : | a new EShellWindow

### e_shell_handle_uris ()

    guint               e_shell_handle_uris                 (EShell *shell,
                                                             const gchar * const *uris,
                                                             gboolean do_import);

Emits the "handle-uri" signal for each URI.

`shell` : | an EShell
`uris` : | `NULL`-terminated list of URIs
`do_import` : | request an import of the URIs
Returns : | the number of URIs successfully handled

### e_shell_submit_alert ()

    void                e_shell_submit_alert                (EShell *shell,
                                                             EAlert *alert);

Broadcasts `alert` to all EShellWindows. This should only be used for application-wide alerts such as a network outage. Submit view-specific alerts to the appropriate EShellContent instance.

`shell` : | an EShell
`alert` : | an EAlert

### e_shell_watch_window ()

    void                e_shell_watch_window                (EShell *shell,
                                                             GtkWindow *window);

Makes `shell` "watch" a newly created toplevel window, and emits the "window-created" signal. All EShellWindows should be watched, along with any editor or viewer windows that may be shown in response to `e_shell_handle_uris()`. When the last watched window is closed, Evolution terminates.

`shell` : | an EShell
`window` : | a GtkWindow

### e_shell_get_watched_windows ()

    GList *		           e_shell_get_watched_windows         (EShell *shell);

Returns a list of windows being watched by `shell`. The list is sorted by the most recently focused window, such that the first instance is the currently focused window. (Useful for choosing a parent for a transient window.) The list is owned by `shell` and should not be modified or freed.

`shell` : | an EShell
Returns : | a list of watched windows

### e_shell_get_active_window ()

    GtkWindow *         e_shell_get_active_window           (EShell *shell);

Returns the most recently focused watched window, according to `e_shell_get_watched_windows()`. Convenient for finding a parent for a transient window.

Note the returned window is not necessarily an EShellWindow.

`shell` : | an EShell or `NULL` to use the default shell
Returns : | the most recently focused watched window

### e_shell_get_meego_mode ()

    gboolean            e_shell_get_meego_mode              (EShell *shell);

Returns `TRUE` if Evolution is in MeeGo mode.

`shell` : | an EShell
Returns : | `TRUE` if Evolution is in MeeGo mode

### e_shell_get_express_mode ()

    gboolean            e_shell_get_express_mode            (EShell *shell);

Returns `TRUE` if Evolution is in express mode.

`shell` : | an EShell
Returns : | `TRUE` if Evolution is in express mode

### e_shell_get_small_screen_mode ()

    gboolean            e_shell_get_small_screen_mode       (EShell *shell);

Returns `TRUE` if Evolution is in small (netbook) screen mode.

`shell` : | an EShell
Returns : | `TRUE` if Evolution is in small screen mode

### e_shell_get_module_directory ()

    const gchar *	      e_shell_get_module_directory        (EShell *shell);

Returns the directory from which EModules were loaded.

`shell` : | an EShell
Returns : | the EModule directory

### e_shell_get_network_available ()

    gboolean            e_shell_get_network_available       (EShell *shell);

Returns `TRUE` if a network is available.

`shell` : | an EShell
Returns : | `TRUE` if a network is available

### e_shell_set_network_available ()

    void                e_shell_set_network_available       (EShell *shell,
                                                             gboolean network_available);

Sets whether a network is available. This is usually called in response to a status change signal from NetworkManager. If the network becomes unavailable while "online" is `TRUE`, the `shell` will force "online" to `FALSE` until the network becomes available again.

`shell` : | an EShell
`network_available` : | whether a network is available

### e_shell_lock_network_available ()

    void                e_shell_lock_network_available      (EShell *shell);

Locks the value of "network-available" to `TRUE`. Further attempts to set the property will be ignored.

This is used for the --force-online command-line option, which is intended to override the network availability status as reported by NetworkManager or other network monitoring software.

`shell` : | an EShell

### e_shell_get_online ()

    gboolean            e_shell_get_online                  (EShell *shell);

Returns `TRUE` if Evolution is online, `FALSE` if Evolution is offline. Evolution may be offline because the user elected to work offline, or because the network has become unavailable.

`shell` : | an EShell
Returns : | `TRUE` if Evolution is online

### e_shell_set_online ()

    void                e_shell_set_online                  (EShell *shell,
                                                             gboolean online);

Asynchronously places Evolution in online or offline mode.

`shell` : | an EShell
`online` : | `TRUE` to go online, `FALSE` to go offline

### e_shell_get_preferences_window ()

    GtkWidget *	        e_shell_get_preferences_window      (EShell *shell);

Returns the Evolution Preferences window.

`shell` : | an EShell
Returns : | the preferences window

### e_shell_event ()

    void                e_shell_event                       (EShell *shell,
                                                             const gchar *event_name,
                                                             gpointer event_data);

The "event" signal acts as a cheap mechanism for broadcasting events to the rest of the application, such as new mail arriving. The `event_name` is used as the signal detail, and `event_data` may point to an object or data structure associated with the event.

`shell` : | an EShell
`event_name` : | the name of the event
`event_data` : | data associated with the event

### enum EShellQuitReason

    typedef enum {
    	E_SHELL_QUIT_ACTION,
    	E_SHELL_QUIT_LAST_WINDOW,
    	E_SHELL_QUIT_OPTION,
    	E_SHELL_QUIT_REMOTE_REQUEST,
    	E_SHELL_QUIT_SESSION_REQUEST
    } EShellQuitReason;

`E_SHELL_QUIT_ACTION`: `E_SHELL_WINDOW_ACTION_QUIT` was activated. `E_SHELL_QUIT_LAST_WINDOW`: The last watched window has been destroyed. `E_SHELL_QUIT_OPTION`: The program was invoked with --quit. Extensions will never see this value because they are not loaded when --quit is given. `E_SHELL_QUIT_REMOTE_REQUEST`: Another Evolution process requested we quit. `E_SHELL_QUIT_SESSION_REQUEST`: The desktop session requested we quit.

These values are passed in the "quit-requested" signal to indicate why the shell is requesting to shut down.

### e_shell_quit ()

    gboolean            e_shell_quit                        (EShell *shell,
                                                             EShellQuitReason reason);

Requests an application shutdown. This happens in two phases: the first is synchronous, the second is asynchronous.

In the first phase, the `shell` emits a "quit-requested" signal to potentially give the user a chance to cancel shutdown. If the user cancels shutdown, the function returns `FALSE`. Otherwise it proceeds into the second phase.

In the second phase, the `shell` emits a "prepare-for-quit" signal and immediately returns `TRUE`. Signal handlers may delay the actual application shutdown while they clean up resources, but there is no way to cancel shutdown at this point.

Consult the documentation for these two signals for details on how to handle them.

`shell` : | an EShell
`reason` : | the reason for quitting
Returns : | `TRUE` if shutdown is underway, `FALSE` if it was cancelled

### e_shell_cancel_quit ()

    void                e_shell_cancel_quit                 (EShell *shell);

This function may only be called from "quit-requested" signal handlers to prevent Evolution from quitting. Calling this will stop further emission of the "quit-requested" signal.

Note: This function has no effect during a "prepare-for-quit" signal emission.

`shell` : | an EShell

### e_shell_adapt_window_size ()

    void                e_shell_adapt_window_size           (EShell *shell,
                                                             GtkWindow *window);

This is used to adapt to window's size to be optimal for the platform. The shell settings are used to determine if a window should be set to full screen etc.

This method is best called when the widget is realized on a given screen.

`shell` : | an EShell
`window` : | a GtkWindow to adapt to full-screen

### e_shell_set_startup_view ()

    void                e_shell_set_startup_view            (EShell *shell,
                                                             const gchar *view);

### e_shell_get_startup_view ()

    const gchar *	      e_shell_get_startup_view            (EShell *shell);

### E_SHELL_MIGRATE_ERROR

    #define             E_SHELL_MIGRATE_ERROR

Error domain for migration operations. Errors in this domain will be from the EShellMigrateError enumeration. See GError for information on error domains.

### enum EShellMigrateError

    typedef enum {
    	E_SHELL_MIGRATE_ERROR_FAILED
    } EShellMigrateError;

### e_shell_migrate_attempt ()

    gboolean            e_shell_migrate_attempt             (EShell *shell);

### e_shell_detect_meego ()

    void                e_shell_detect_meego                (gboolean *is_meego,
                                                             gboolean *small_screen);

## Property Details

### The `"express-mode"` property

      "express-mode"             gboolean              : Read / Write / Construct Only

Express mode alters Evolution's user interface to be more usable on devices with small screens.

Default value: FALSE

### The `"geometry"` property

      "geometry"                 gchar*                : Write / Construct Only

User-specified initial window geometry string to apply to the first EShellWindow created.

Default value: NULL

### The `"meego-mode"` property

      "meego-mode"               gboolean              : Read / Write / Construct Only

Whether meego mode is enabled.

Default value: FALSE

### The `"module-directory"` property

      "module-directory"         gchar*                : Read / Write / Construct Only

The directory from which to load EModules.

Default value: NULL

### The `"network-available"` property

      "network-available"        gboolean              : Read / Write / Construct

Whether the network is available.

Default value: TRUE

### The `"online"` property

      "online"                   gboolean              : Read / Write / Construct

Whether the shell is online.

Default value: FALSE

### The `"shell-settings"` property

      "shell-settings"           EShellSettings*       : Read

Application-wide settings.

### The `"small-screen-mode"` property

      "small-screen-mode"        gboolean              : Read / Write / Construct Only

Whether we run on a rather small screen.

Default value: FALSE

## Signal Details

### The `"event"` signal

    void                user_function                      (EShell  *shell,
                                                            gpointer event_data,
                                                            gpointer user_data)       : Action

This signal is used to broadcast custom events to the entire application. The nature of `event_data` depends on the event being broadcast. The signal's detail denotes the event.

`shell` : | the EShell which emitted the signal
`event_data` : | data associated with the event
`user_data` : | user data set when the signal handler was connected.

### The `"handle-uri"` signal

    gboolean            user_function                      (EShell  *shell,
                                                            gchar   *uri,
                                                            gpointer user_data)      : Action

Emitted when `shell` receives a URI to be handled, usually by way of a command-line argument. An EShellBackend should listen for this signal and try to handle the URI, usually by opening an editor window for the identified resource.

`shell` : | the EShell which emitted the signal
`uri` : | the URI to be handled
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` if the URI could be handled, `FALSE` otherwise

### The `"prepare-for-offline"` signal

    void                user_function                      (EShell    *shell,
                                                            EActivity *activity,
                                                            gpointer   user_data)      : Run First

Emitted when the user elects to work offline. An EShellBackend should listen for this signal and make preparations for working in offline mode.

If preparations for working offline cannot immediately be completed (such as when synchronizing with a remote server), the EShellBackend should reference the `activity` until preparations are complete, and then unreference the `activity`. This will delay Evolution from actually going to offline mode until all backends have unreferenced `activity`.

`shell` : | the EShell which emitted the signal
`activity` : | the EActivity for offline preparations
`user_data` : | user data set when the signal handler was connected.

### The `"prepare-for-online"` signal

    void                user_function                      (EShell    *shell,
                                                            EActivity *activity,
                                                            gpointer   user_data)      : Run First

Emitted when the user elects to work online. An EShellBackend should listen for this signal and make preparations for working in online mode.

If preparations for working online cannot immediately be completed (such as when re-connecting to a remote server), the EShellBackend should reference the `activity` until preparations are complete, and then unreference the `activity`. This will delay Evolution from actually going to online mode until all backends have unreferenced `activity`.

`shell` : | the EShell which emitted the signal
`activity` : | the EActivity for offline preparations
`user_data` : | user data set when the signal handler was connected.

### The `"prepare-for-quit"` signal

    void                user_function                      (EShell    *shell,
                                                            EActivity *activity,
                                                            gpointer   user_data)      : Run First

Emitted when the user elects to quit the application, after "quit-requested". An EShellBackend should listen for this signal and make preparations for shutting down.

If preparations for shutting down cannot immediately be completed (such as when there are uncompleted network operations), the EShellBackend should reference the `activity` until preparations are complete, and then unreference the `activity`. This will delay Evolution from actually shutting down until all backends have unreferenced `activity`.

`shell` : | the EShell which emitted the signal
`activity` : | the EActivity for quit preparations
`user_data` : | user data set when the signal handler was connected.

### The `"quit-requested"` signal

    void                user_function                      (EShell          *shell,
                                                            EShellQuitReason reason,
                                                            gpointer         user_data)      : Run First

Emitted when the user elects to quit the application, before "prepare-for-quit".

EShellBackends and editor windows can listen for this signal to prompt the user to save changes or finish scheduled operations immediately (such as sending mail in Outbox). If the user elects to cancel, the signal handler should call `e_shell_cancel_quit()` to abort the quit.

`shell` : | the EShell which emitted the signal
`reason` : | the reason for quitting
`user_data` : | user data set when the signal handler was connected.

### The `"window-created"` signal

    void                user_function                      (EShell    *shell,
                                                            GtkWindow *window,
                                                            gpointer   user_data)      : Run Last

Emitted when `shell` begins watching a newly created window.

`shell` : | the EShell which emitted the signal
`window` : | the newly created GtkWindow
`user_data` : | user data set when the signal handler was connected.

### The `"window-destroyed"` signal

    void                user_function                      (EShell  *shell,
                                                            gpointer user_data)      : Run Last

Emitted when a watched is destroyed.

`shell` : | the EShell which emitted the signal
`user_data` : | user data set when the signal handler was connected.