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 ()
GtkAction * | e_shell_window_get_shell_view_action ()
GtkWidget * | e_shell_window_get_alert_bar ()
EFocusTracker * | e_shell_window_get_focus_tracker ()
GtkUIManager * | e_shell_window_get_ui_manager ()
GtkAction * | e_shell_window_get_action ()
void | e_shell_window_add_action_group_full ()
GtkActionGroup * | e_shell_window_get_action_group ()
GtkWidget * | e_shell_window_get_managed_widget ()
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 ()
gboolean | e_shell_window_get_menubar_visible ()
void | e_shell_window_set_menubar_visible ()
gboolean | e_shell_window_get_sidebar_visible ()
void | e_shell_window_set_sidebar_visible ()
gboolean | e_shell_window_get_switcher_visible ()
void | e_shell_window_set_switcher_visible ()
gboolean | e_shell_window_get_taskbar_visible ()
void | e_shell_window_set_taskbar_visible ()
gboolean | e_shell_window_get_toolbar_visible ()
void | e_shell_window_set_toolbar_visible ()
void | (*EShellWindowConnetClientFunc) ()
void | e_shell_window_connect_client ()
gboolean | e_shell_window_get_need_input ()
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 | menubar-visible | Read / Write
gboolean | safe-mode | Read / Write / Construct
EShell * | shell | Read / Write / Construct Only
gboolean | sidebar-visible | Read / Write
gboolean | switcher-visible | Read / Write
gboolean | taskbar-visible | Read / Write
gboolean | toolbar-visible | Read / Write
GtkUIManager * | ui-manager | Read

## 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 ()

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

Returns the switcher action for `view_name` .

An EShellWindow creates a GtkRadioAction 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_manager ()

    GtkUIManager *
    e_shell_window_get_ui_manager (EShellWindow *shell_window);

Returns `shell_window` 's user interface manager, which manages the window's menus and toolbars via GtkActions. This is the mechanism by which shell views and plugins can extend Evolution's menus and toolbars.

#### Parameters

shell_window | an EShellWindow |

#### Returns

the GtkUIManager for `shell_window`

### e_shell_window_get_action ()

    GtkAction *
    e_shell_window_get_action (EShellWindow *shell_window,
                               const gchar *action_name);

Returns the GtkAction named `action_name` in `shell_window` 's user interface manager, or `NULL` if no such action exists.

#### Parameters

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

#### Returns

the GtkAction named `action_name`

### e_shell_window_add_action_group_full ()

    void
    e_shell_window_add_action_group_full (EShellWindow *shell_window,
                                          const gchar *group_name,
                                          const gchar *for_view_name);

### e_shell_window_get_action_group ()

    GtkActionGroup *
    e_shell_window_get_action_group (EShellWindow *shell_window,
                                     const gchar *group_name);

Returns the GtkActionGroup named `group_name` in `shell_window` 's user interface manager, or `NULL` if no such action group exists.

#### Parameters

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

#### Returns

the GtkActionGroup named `group_name`

### e_shell_window_get_managed_widget ()

    GtkWidget *
    e_shell_window_get_managed_widget (EShellWindow *shell_window,
                                       const gchar *widget_path);

Looks up a widget in `shell_window` 's user interface manager by following a path. See `gtk_ui_manager_get_widget()` for more information about paths.

#### Parameters

shell_window | an EShellWindow |
widget_path | path in the UI definition |

#### Returns

the widget found by following the path, or `NULL` if no widget was found

### 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);

Creates a new GtkActionGroup and adds it to `shell_window` 's user interface manager. This also takes care of details like setting the translation domain.

#### Parameters

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

### e_shell_window_get_menubar_visible ()

    gboolean
    e_shell_window_get_menubar_visible (EShellWindow *shell_window);

Returns `TRUE` if `shell_window` 's menu bar is visible.

#### Parameters

shell_window | an EShellWindow |

#### Returns

`TRUE` is the menu bar is visible

Since: 3.24

### e_shell_window_set_menubar_visible ()

    void
    e_shell_window_set_menubar_visible (EShellWindow *shell_window,
                                        gboolean menubar_visible);

Makes `shell_window` 's menu bar visible or invisible.

#### Parameters

shell_window | an EShellWindow |
menubar_visible | whether the menu bar should be visible |

Since: 3.24

### e_shell_window_get_sidebar_visible ()

    gboolean
    e_shell_window_get_sidebar_visible (EShellWindow *shell_window);

Returns `TRUE` if `shell_window` 's side bar is visible.

#### Parameters

shell_window | an EShellWindow |

#### Returns

`TRUE` is the side bar is visible

### e_shell_window_set_sidebar_visible ()

    void
    e_shell_window_set_sidebar_visible (EShellWindow *shell_window,
                                        gboolean sidebar_visible);

Makes `shell_window` 's side bar visible or invisible.

#### Parameters

shell_window | an EShellWindow |
sidebar_visible | whether the side bar should be visible |

### e_shell_window_get_switcher_visible ()

    gboolean
    e_shell_window_get_switcher_visible (EShellWindow *shell_window);

Returns `TRUE` if `shell_window` 's switcher buttons are visible.

#### Parameters

shell_window | an EShellWindow |

#### Returns

`TRUE` is the switcher buttons are visible

### e_shell_window_set_switcher_visible ()

    void
    e_shell_window_set_switcher_visible (EShellWindow *shell_window,
                                         gboolean switcher_visible);

Makes `shell_window` 's switcher buttons visible or invisible.

#### Parameters

shell_window | an EShellWindow |
switcher_visible | whether the switcher buttons should be visible |

### e_shell_window_get_taskbar_visible ()

    gboolean
    e_shell_window_get_taskbar_visible (EShellWindow *shell_window);

Returns `TRUE` if `shell_window` 's task bar is visible.

#### Parameters

shell_window | an EShellWindow |

#### Returns

`TRUE` is the task bar is visible

### e_shell_window_set_taskbar_visible ()

    void
    e_shell_window_set_taskbar_visible (EShellWindow *shell_window,
                                        gboolean taskbar_visible);

Makes `shell_window` 's task bar visible or invisible.

#### Parameters

shell_window | an EShellWindow |
taskbar_visible | whether the task bar should be visible |

### e_shell_window_get_toolbar_visible ()

    gboolean
    e_shell_window_get_toolbar_visible (EShellWindow *shell_window);

Returns `TRUE` if `shell_window` 's tool bar is visible.

#### Parameters

shell_window | an EShellWindow |

#### Returns

`TRUE` if the tool bar is visible

### e_shell_window_set_toolbar_visible ()

    void
    e_shell_window_set_toolbar_visible (EShellWindow *shell_window,
                                        gboolean toolbar_visible);

Makes `shell_window` 's tool bar visible or invisible.

#### Parameters

shell_window | an EShellWindow |
toolbar_visible | whether the tool bar should be visible |

### 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_get_need_input ()

    gboolean
    e_shell_window_get_need_input (EShellWindow *shell_window,
                                   GdkEventKey *event);

#### Parameters

shell_window | an EShellWindow |
event | a GdkEventKey |

#### Returns

Whether the key `event` should be processed by currently focused widget in the `window` , instead of being processed bu usual means including accelerators.

Since: 3.32

### e_shell_window_register_new_item_actions ()

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

Registers a list of GtkActions 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 GtkActions 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 GtkActionEntrys |
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,
                                    GtkActionEntry *entries,
                                    guint n_entries);

Registers a list of GtkActions 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 GtkActions 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 GtkActionEntrys |
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 `“menubar-visible”` property

      “menubar-visible”          gboolean

Whether the shell window's menu bar is visible.

Owner: EShellWindow

Flags: Read / Write

Default value: TRUE

Since: 3.24

### 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

### The `“sidebar-visible”` property

      “sidebar-visible”          gboolean

Whether the shell window's side bar is visible.

Owner: EShellWindow

Flags: Read / Write

Default value: TRUE

### The `“switcher-visible”` property

      “switcher-visible”         gboolean

Whether the shell window's switcher buttons are visible.

Owner: EShellWindow

Flags: Read / Write

Default value: TRUE

### The `“taskbar-visible”` property

      “taskbar-visible”          gboolean

Whether the shell window's task bar is visible.

Owner: EShellWindow

Flags: Read / Write

Default value: TRUE

### The `“toolbar-visible”` property

      “toolbar-visible”          gboolean

Whether the shell window's tool bar is visible.

Owner: EShellWindow

Flags: Read / Write

Default value: TRUE

### The `“ui-manager”` property

      “ui-manager”               GtkUIManager *

The shell window's GtkUIManager.

Owner: EShellWindow

Flags: Read

## 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