EShellWindow

## EShellWindow EShellWindow — the main window |

## Synopsis

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

    struct              EShellWindow;
    GtkWidget *	        e_shell_window_new                  (EShell *shell,
                                                             gboolean safe_mode,
                                                             const gchar *geometry);
    EShell *	           e_shell_window_get_shell            (EShellWindow *shell_window);
    struct _EShellView * e_shell_window_get_shell_view      (EShellWindow *shell_window,
                                                             const gchar *view_name);
    struct _EShellView * e_shell_window_peek_shell_view     (EShellWindow *shell_window,
                                                             const gchar *view_name);
    GtkAction *         e_shell_window_get_shell_view_action
                                                            (EShellWindow *shell_window,
                                                             const gchar *view_name);
    GtkWidget *	        e_shell_window_get_alert_bar        (EShellWindow *shell_window);
    EFocusTracker *     e_shell_window_get_focus_tracker    (EShellWindow *shell_window);
    GtkUIManager *	     e_shell_window_get_ui_manager       (EShellWindow *shell_window);
    GtkAction *	        e_shell_window_get_action           (EShellWindow *shell_window,
                                                             const gchar *action_name);
    GtkActionGroup *    e_shell_window_get_action_group     (EShellWindow *shell_window,
                                                             const gchar *group_name);
    GtkWidget *         e_shell_window_get_managed_widget   (EShellWindow *shell_window,
                                                             const gchar *widget_path);
    const gchar *	      e_shell_window_get_active_view      (EShellWindow *shell_window);
    void                e_shell_window_set_active_view      (EShellWindow *shell_window,
                                                             const gchar *view_name);
    gboolean            e_shell_window_get_safe_mode        (EShellWindow *shell_window);
    void                e_shell_window_set_safe_mode        (EShellWindow *shell_window,
                                                             gboolean safe_mode);
    void                e_shell_window_add_action_group     (EShellWindow *shell_window,
                                                             const gchar *group_name);
    gboolean            e_shell_window_get_sidebar_visible  (EShellWindow *shell_window);
    void                e_shell_window_set_sidebar_visible  (EShellWindow *shell_window,
                                                             gboolean sidebar_visible);
    gboolean            e_shell_window_get_switcher_visible (EShellWindow *shell_window);
    void                e_shell_window_set_switcher_visible (EShellWindow *shell_window,
                                                             gboolean switcher_visible);
    gboolean            e_shell_window_get_taskbar_visible  (EShellWindow *shell_window);
    void                e_shell_window_set_taskbar_visible  (EShellWindow *shell_window,
                                                             gboolean taskbar_visible);
    gboolean            e_shell_window_get_toolbar_visible  (EShellWindow *shell_window);
    void                e_shell_window_set_toolbar_visible  (EShellWindow *shell_window,
                                                             gboolean toolbar_visible);
    void                e_shell_window_register_new_item_actions
                                                            (EShellWindow *shell_window,
                                                             const gchar *backend_name,
                                                             GtkActionEntry *entries,
                                                             guint n_entries);
    void                e_shell_window_register_new_source_actions
                                                            (EShellWindow *shell_window,
                                                             const gchar *backend_name,
                                                             GtkActionEntry *entries,
                                                             guint n_entries);
    GtkWidget *	        e_shell_window_get_menu_bar_box     (EShellWindow *shell_window);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkWindow
                                     +----EShellWindow

## Implemented Interfaces

EShellWindow implements AtkImplementorIface, GtkBuildable, EAlertSink and EExtensible.

## Properties

      "active-view"              gchar*                : Read / Write
      "alert-bar"                EAlertBar*            : Read
      "focus-tracker"            EFocusTracker*        : Read
      "geometry"                 gchar*                : Write / Construct Only
      "safe-mode"                gboolean              : Read / Write / Construct
      "shell"                    EShell*               : Read / Write / Construct Only
      "sidebar-visible"          gboolean              : Read / Write
      "switcher-visible"         gboolean              : Read / Write
      "taskbar-visible"          gboolean              : Read / Write
      "toolbar-visible"          gboolean              : Read / Write
      "ui-manager"               GtkUIManager*         : Read

## Signals

      "shell-view-created"                             : Has Details

## Description

## Details

### struct EShellWindow

    struct EShellWindow;

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

### 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 GConf key `/apps/evolution/shell/view_defaults/component_id`. Or, if the GConf key is not set or can't be read, the first view in the switcher is used.

`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()`.

`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 `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 a "shell-view-created" signal with `view_name` as the signal detail when it instantiates an EShellView.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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 GConf key `/apps/evolution/shell/view_defaults/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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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 GtkActions to appear in `shell_window`'s "New" menu and toolbar button. This function should be called from an EShell's "window-created" 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.

`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-created" 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.

`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_get_menu_bar_box ()

    GtkWidget *	        e_shell_window_get_menu_bar_box     (EShellWindow *shell_window);

## Property Details

### The `"active-view"` property

      "active-view"              gchar*                : Read / Write

Name of the active EShellView.

Default value: NULL

### The `"alert-bar"` property

      "alert-bar"                EAlertBar*            : Read

Displays informational and error messages.

### The `"focus-tracker"` property

      "focus-tracker"            EFocusTracker*        : Read

The shell window's EFocusTracker.

### The `"geometry"` property

      "geometry"                 gchar*                : Write / Construct Only

User-specified initial window geometry string.

Default value: NULL

### The `"safe-mode"` property

      "safe-mode"                gboolean              : Read / Write / Construct

Whether the shell window is in safe mode.

Default value: FALSE

### The `"shell"` property

      "shell"                    EShell*               : Read / Write / Construct Only

The EShell singleton.

### The `"sidebar-visible"` property

      "sidebar-visible"          gboolean              : Read / Write

Whether the shell window's side bar is visible.

Default value: TRUE

### The `"switcher-visible"` property

      "switcher-visible"         gboolean              : Read / Write

Whether the shell window's switcher buttons are visible.

Default value: TRUE

### The `"taskbar-visible"` property

      "taskbar-visible"          gboolean              : Read / Write

Whether the shell window's task bar is visible.

Default value: TRUE

### The `"toolbar-visible"` property

      "toolbar-visible"          gboolean              : Read / Write

Whether the shell window's tool bar is visible.

Default value: TRUE

### The `"ui-manager"` property

      "ui-manager"               GtkUIManager*         : Read

The shell window's GtkUIManager.

## Signal Details

### The `"shell-view-created"` signal

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

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.

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