EShellWindow: Evolution Shell Reference Manual

## EShellWindow EShellWindow — the main window |

## Functions

GtkWidget * | e_shell_window_new ()
EShell * | e_shell_window_get_shell ()
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 ()
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_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 | e_shell_window_register_new_item_actions ()
void | e_shell_window_register_new_source_actions ()

## Properties

gchar * | active-view | Read / Write
EAlertBar * | alert-bar | Read
EFocusTracker * | focus-tracker | Read
gchar * | geometry | Write / Construct Only
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

## 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 <filename>/org/gnome/evolution/shell/default-component-id</filename>. 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_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 <structfield>name</structfield> 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 a “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 <structfield>name</structfield> 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 GtkAction<!-- -->s. 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_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 definintion |

#### 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 <filename>/org/gnome/evolution/shell/default-component-id</filename>. 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_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 |

### 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 GtkAction<!-- -->s 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 <structfield>name</structfield> field from its own EShellBackendInfo).

The registered GtkAction<!-- -->s 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 GtkActionEntry<!-- -->s |
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 GtkAction<!-- -->s 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 <structfield>name</structfield> field from its own EShellBackendInfo).

The registered GtkAction<!-- -->s 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 GtkActionEntry<!-- -->s |
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”              gchar *

Name of the active EShellView.

Flags: Read / Write

Default value: NULL

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

      “alert-bar”                EAlertBar *

Displays informational and error messages.

Flags: Read

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

      “focus-tracker”            EFocusTracker *

The shell window's EFocusTracker.

Flags: Read

### The `“geometry”` property

      “geometry”                 gchar *

User-specified initial window geometry string.

Flags: Write / Construct Only

Default value: NULL

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

      “safe-mode”                gboolean

Whether the shell window is in safe mode.

Flags: Read / Write / Construct

Default value: FALSE

### The `“shell”` property

      “shell”                    EShell *

The EShell singleton.

Flags: Read / Write / Construct Only

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

      “sidebar-visible”          gboolean

Whether the shell window's side bar is visible.

Flags: Read / Write

Default value: TRUE

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

      “switcher-visible”         gboolean

Whether the shell window's switcher buttons are visible.

Flags: Read / Write

Default value: TRUE

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

      “taskbar-visible”          gboolean

Whether the shell window's task bar is visible.

Flags: Read / Write

Default value: TRUE

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

      “toolbar-visible”          gboolean

Whether the shell window's tool bar is visible.

Flags: Read / Write

Default value: TRUE

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

      “ui-manager”               GtkUIManager *

The shell window's GtkUIManager.

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