EShellWindow: Evolution Shell Reference Manual

## EShellWindow EShellWindow — the main window |

## Functions

GtkWidget * | e_shell_window_new ()
EShell * | e_shell_window_get_shell ()
gboolean | e_shell_window_is_main_instance ()
struct _EShellView * | e_shell_window_get_shell_view ()
struct _EShellView * | e_shell_window_peek_shell_view ()
EUIAction * | e_shell_window_get_shell_view_action ()
GtkWidget * | e_shell_window_get_alert_bar ()
EFocusTracker * | e_shell_window_get_focus_tracker ()
EUIAction * | e_shell_window_get_ui_action ()
EUIActionGroup * | e_shell_window_get_ui_action_group ()
const gchar * | e_shell_window_get_active_view ()
void | e_shell_window_set_active_view ()
gboolean | e_shell_window_get_safe_mode ()
void | e_shell_window_set_safe_mode ()
void | e_shell_window_add_action_group ()
void | (*EShellWindowConnetClientFunc) ()
void | e_shell_window_connect_client ()
void | e_shell_window_register_new_item_actions ()
void | e_shell_window_register_new_source_actions ()

## Properties

char * | active-view | Read / Write
EAlertBar * | alert-bar | Read
EFocusTracker * | focus-tracker | Read
char * | geometry | Write / Construct Only
gboolean | safe-mode | Read / Write / Construct
EShell * | shell | Read / Write / Construct Only

## Signals

void | close-alert | Action
void | shell-view-created | Has Details
void | update-new-menu | Action

## Types and Values

struct | EShellWindow

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkWindow
                            ╰── EShellWindow

## Implemented Interfaces

EShellWindow implements AtkImplementorIface, GtkBuildable, EAlertSink and EExtensible.

## Includes

    #include <shell/e-shell-window.h>

## Description

## Functions

### e_shell_window_new ()

    GtkWidget *
    e_shell_window_new (EShell *shell,
                        gboolean safe_mode,
                        const gchar *geometry);

Returns a new EShellWindow.

It's up to the various EShellView's to define exactly what "safe mode" means, but the EShell usually puts the initial EShellWindow into "safe mode" if detects the previous Evolution session crashed.

The initial view for the window is determined by GSettings key `/org/gnome/evolution/shell/default-component-id`. Or, if the GSettings key is not set or can't be read, the first view in the switcher is used.

#### Parameters

shell | an EShell |
safe_mode | whether to initialize the window to "safe mode" |
geometry | initial window geometry string, or `NULL` |

#### Returns

a new EShellWindow

### e_shell_window_get_shell ()

    EShell *
    e_shell_window_get_shell (EShellWindow *shell_window);

Returns the EShell that was passed to `e_shell_window_new()`.

#### Parameters

shell_window | an EShellWindow |

#### Returns

the EShell

### e_shell_window_is_main_instance ()

    gboolean
    e_shell_window_is_main_instance (EShellWindow *shell_window);

Returns, whether the `shell_window` is the main instance, which is the window which was created as the first `shell_window` .

#### Parameters

shell_window | an EShellWindow |

#### Returns

whether the `shell_window` is the main instance

### e_shell_window_get_shell_view ()

    struct _EShellView *
    e_shell_window_get_shell_view (EShellWindow *shell_window,
                                   const gchar *view_name);

Returns the EShellView named `view_name` (see the `name` field in EShellBackendInfo). This will also instantiate the EShellView the first time it's requested. To reduce resource consumption, Evolution tries to delay instantiating shell views until the user switches to them. So in general, only the active view name, as returned by `e_shell_window_get_active_view()`, should be requested.

The function emits an “shell-view-created” signal with `view_name` as the signal detail when it instantiates an EShellView.

#### Parameters

shell_window | an EShellWindow |
view_name | name of a shell view |

#### Returns

the requested EShellView, or `NULL` if no such view is registered

### e_shell_window_peek_shell_view ()

    struct _EShellView *
    e_shell_window_peek_shell_view (EShellWindow *shell_window,
                                    const gchar *view_name);

Returns the EShellView named `view_name` (see the `name` field in EShellBackendInfo), or `NULL` if the requested view has not yet been instantiated. Unlike `e_shell_window_get_shell_view()`, this function will not instantiate the view itself.

#### Parameters

shell_window | an EShellWindow |
view_name | name of a shell view |

#### Returns

the requested EShellView, or `NULL` if no such view is instantiated

### e_shell_window_get_shell_view_action ()

    EUIAction *
    e_shell_window_get_shell_view_action (EShellWindow *shell_window,
                                          const gchar *view_name);

Returns the switcher action for `view_name` .

An EShellWindow creates an EUIAction for each registered subclass of EShellView. This action gets passed to the EShellSwitcher, which displays a button that proxies the action. When the EShellView named `view_name` is active, the action's icon becomes the `shell_window` icon.

#### Parameters

shell_window | an EShellWindow |
view_name | name of a shell view |

#### Returns

the switcher action for the EShellView named `view_name` , or `NULL` if no such shell view exists

### e_shell_window_get_alert_bar ()

    GtkWidget *
    e_shell_window_get_alert_bar (EShellWindow *shell_window);

Returns the EAlertBar used to display informational and error messages.

#### Parameters

shell_window | an EShellWindow |

#### Returns

the EAlertBar for `shell_window`

### e_shell_window_get_focus_tracker ()

    EFocusTracker *
    e_shell_window_get_focus_tracker (EShellWindow *shell_window);

Returns `shell_window` 's focus tracker, which directs Cut, Copy, Paste and Select All main menu activations to the appropriate editable or selectable widget.

#### Parameters

shell_window | an EShellWindow |

#### Returns

the EFocusTracker for `shell_window`

### e_shell_window_get_ui_action ()

    EUIAction *
    e_shell_window_get_ui_action (EShellWindow *shell_window,
                                  const gchar *action_name);

Returns the EUIAction named `action_name` provided by the `shell_window` itself, or `NULL` if no such action exists.

#### Parameters

shell_window | an EShellWindow |
action_name | the name of an action |

#### Returns

the EUIAction named `action_name` , or `NULL` if not found.

[transfer none][nullable]

Since: 3.56

### e_shell_window_get_ui_action_group ()

    EUIActionGroup *
    e_shell_window_get_ui_action_group (EShellWindow *shell_window,
                                        const gchar *group_name);

Returns the EUIActionGroup named `group_name` provided by the `shell_window` itself, or `NULL` if no such action group exists.

#### Parameters

shell_window | an EShellWindow |
group_name | the name of an action group |

#### Returns

the EUIActionGroup named `group_name` , or `NULL` if not found.

[transfer none][nullable]

Since: 3.56

### e_shell_window_get_active_view ()

    const gchar *
    e_shell_window_get_active_view (EShellWindow *shell_window);

Returns the name of the active EShellView.

#### Parameters

shell_window | an EShellWindow |

#### Returns

the name of the active view

### e_shell_window_set_active_view ()

    void
    e_shell_window_set_active_view (EShellWindow *shell_window,
                                    const gchar *view_name);

Switches `shell_window` to the EShellView named `view_name` , causing the entire content of `shell_window` to change. This is typically called as a result of the user clicking one of the switcher buttons.

The name of the newly activated shell view is also written to GSettings key `/org/gnome/evolution/shell/default-component-id`. This makes the active shell view persistent across Evolution sessions. It also causes new shell windows created within the current Evolution session to open to the most recently selected shell view.

#### Parameters

shell_window | an EShellWindow |
view_name | the name of the shell view to switch to |

### e_shell_window_get_safe_mode ()

    gboolean
    e_shell_window_get_safe_mode (EShellWindow *shell_window);

Returns `TRUE` if `shell_window` is in "safe mode".

It's up to the various EShellView's to define exactly what "safe mode" means. The `shell_window` simply manages the "safe mode" state.

#### Parameters

shell_window | an EShellWindow |

#### Returns

`TRUE` if `shell_window` is in "safe mode"

### e_shell_window_set_safe_mode ()

    void
    e_shell_window_set_safe_mode (EShellWindow *shell_window,
                                  gboolean safe_mode);

If `TRUE`, puts `shell_window` into "safe mode".

It's up to the various EShellView's to define exactly what "safe mode" means. The `shell_window` simply manages the "safe mode" state.

#### Parameters

shell_window | an EShellWindow |
safe_mode | whether to put `shell_window` into "safe mode" |

### e_shell_window_add_action_group ()

    void
    e_shell_window_add_action_group (EShellWindow *shell_window,
                                     const gchar *group_name);

### EShellWindowConnetClientFunc ()

    void
    (*EShellWindowConnetClientFunc) (EShellWindow *shell_window,
                                     EClient *client,
                                     gpointer user_data);

### e_shell_window_connect_client ()

    void
    e_shell_window_connect_client (EShellWindow *shell_window,
                                   ESource *source,
                                   const gchar *extension_name,
                                   EShellWindowConnetClientFunc connected_cb,
                                   gpointer user_data,
                                   GDestroyNotify destroy_user_data);

Get's an EClient from shell's EClientCache in a dedicated thread, thus the operation doesn't block UI. The `connected_cb` is called in the main thread, but only when the operation succeeded. Any failure is propageted to UI.

#### Parameters

shell_window | an EShellWindow |
source | an ESource to connect to |
extension_name | an extension name |
connected_cb | a callback to be called when the client is opened |
user_data | a user data passed to `connected_cb` |
destroy_user_data | callback to free `user_data` when no longer needed. | [allow none]

Since: 3.16

### e_shell_window_register_new_item_actions ()

    void
    e_shell_window_register_new_item_actions
                                   (EShellWindow *shell_window,
                                    const gchar *backend_name,
                                    const EUIActionEntry *entries,
                                    guint n_entries);

Registers a list of EUIActions to appear in `shell_window` 's "New" menu and toolbar button. This function should be called from an EShell's “window-added” signal handler. The EShellBackend calling this function should pass its own name for the `backend_name` argument (i.e. the `name` field from its own EShellBackendInfo).

The registered EUIActions should be for creating individual items such as an email message or a calendar appointment. The action labels should be marked for translation with the "New" context using the `NC_()` macro.

#### Parameters

shell_window | an EShellWindow |
backend_name | name of an EShellBackend |
entries | an array of EUIActionEntrys |
n_entries | number of elements in the array |

### e_shell_window_register_new_source_actions ()

    void
    e_shell_window_register_new_source_actions
                                   (EShellWindow *shell_window,
                                    const gchar *backend_name,
                                    const EUIActionEntry *entries,
                                    guint n_entries);

Registers a list of EUIActions to appear in `shell_window` 's "New" menu and toolbar button. This function should be called from an EShell's “window-added” signal handler. The EShellBackend calling this function should pass its own name for the `backend_name` argument (i.e. the `name` field from its own EShellBackendInfo).

The registered EUIActions should be for creating item containers such as an email folder or a calendar. The action labels should be marked for translation with the "New" context using the `NC_()` macro.

#### Parameters

shell_window | an EShellWindow |
backend_name | name of an EShellBackend |
entries | an array of EUIActionEntrys |
n_entries | number of elements in the array |

## Types and Values

### struct EShellWindow

    struct EShellWindow;

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

## Property Details

### The `“active-view”` property

      “active-view”              char *

Name of the active EShellView.

Owner: EShellWindow

Flags: Read / Write

Default value: NULL

### The `“alert-bar”` property

      “alert-bar”                EAlertBar *

Displays informational and error messages.

Owner: EShellWindow

Flags: Read

### The `“focus-tracker”` property

      “focus-tracker”            EFocusTracker *

The shell window's EFocusTracker.

Owner: EShellWindow

Flags: Read

### The `“geometry”` property

      “geometry”                 char *

User-specified initial window geometry string.

Owner: EShellWindow

Flags: Write / Construct Only

Default value: NULL

### The `“safe-mode”` property

      “safe-mode”                gboolean

Whether the shell window is in safe mode.

Owner: EShellWindow

Flags: Read / Write / Construct

Default value: FALSE

### The `“shell”` property

      “shell”                    EShell *

The EShell singleton.

Owner: EShellWindow

Flags: Read / Write / Construct Only

## Signal Details

### The `“close-alert”` signal

    void
    user_function (EShellWindow *shell_window,
                   gpointer      user_data)

Closes either one EShellView-specific EAlert or else one global EAlert. This signal is bound to the Escape key.

#### Parameters

shell_window | the EShellWindow which emitted the signal |
user_data | user data set when the signal handler was connected. |

Flags: Action

### The `“shell-view-created”` signal

    void
    user_function (EShellWindow *shell_window,
                   EShellView   *shell_view,
                   gpointer      user_data)

Emitted when a new EShellView is instantiated by way of `e_shell_window_get_shell_view()`. The signal detail denotes the new view name, which can be used to obtain notification of when a particular EShellView is created.

#### Parameters

shell_window | the EShellWindow which emitted the signal |
shell_view | the new EShellView |
user_data | user data set when the signal handler was connected. |

Flags: Has Details

### The `“update-new-menu”` signal

    void
    user_function (EShellWindow *shell_window,
                   gpointer      user_data)

Emitted when the 'New' menu should be updated.

#### Parameters

shell_window | the EShellWindow |
user_data | user data set when the signal handler was connected. |

Flags: Action

Since: 3.46