## EShellView EShellView — views within the main window |

## Synopsis

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

    struct              EShellView;
    struct              EShellViewClass;
    const gchar *       e_shell_view_get_name               (EShellView *shell_view);
    GtkAction *         e_shell_view_get_action             (EShellView *shell_view);
    const gchar *       e_shell_view_get_title              (EShellView *shell_view);
    void                e_shell_view_set_title              (EShellView *shell_view,
                                                             const gchar *title);
    const gchar *       e_shell_view_get_view_id            (EShellView *shell_view);
    void                e_shell_view_set_view_id            (EShellView *shell_view,
                                                             const gchar *view_id);
    gboolean            e_shell_view_is_active              (EShellView *shell_view);
    gint                e_shell_view_get_page_num           (EShellView *shell_view);
    void                e_shell_view_set_page_num           (EShellView *shell_view,
                                                             gint page_num);
    GtkWidget *         e_shell_view_get_searchbar          (EShellView *shell_view);
    gchar *             e_shell_view_get_search_name        (EShellView *shell_view);
    EFilterRule *       e_shell_view_get_search_rule        (EShellView *shell_view);
    void                e_shell_view_set_search_rule        (EShellView *shell_view,
                                                             EFilterRule *search_rule);
    gchar *             e_shell_view_get_search_query       (EShellView *shell_view);
    GtkSizeGroup *      e_shell_view_get_size_group         (EShellView *shell_view);
    EShellBackend *     e_shell_view_get_shell_backend      (EShellView *shell_view);
    EShellContent *     e_shell_view_get_shell_content      (EShellView *shell_view);
    EShellSidebar *     e_shell_view_get_shell_sidebar      (EShellView *shell_view);
    EShellTaskbar *     e_shell_view_get_shell_taskbar      (EShellView *shell_view);
    EShellWindow *      e_shell_view_get_shell_window       (EShellView *shell_view);
    GKeyFile *          e_shell_view_get_state_key_file     (EShellView *shell_view);
    void                e_shell_view_set_state_dirty        (EShellView *shell_view);
    void                e_shell_view_clear_search           (EShellView *shell_view);
    void                e_shell_view_custom_search          (EShellView *shell_view,
                                                             EFilterRule *custom_rule);
    void                e_shell_view_execute_search         (EShellView *shell_view);
    void                e_shell_view_block_execute_search   (EShellView *shell_view);
    void                e_shell_view_unblock_execute_search (EShellView *shell_view);
    void                e_shell_view_update_actions         (EShellView *shell_view);
    void                e_shell_view_block_update_actions   (EShellView *shell_view);
    void                e_shell_view_unblock_update_actions (EShellView *shell_view);
    GtkWidget *         e_shell_view_show_popup_menu        (EShellView *shell_view,
                                                             const gchar *widget_path,
                                                             GdkEventButton *event);
    GalViewInstance *   e_shell_view_new_view_instance      (EShellView *shell_view,
                                                             const gchar *instance_id);

## Object Hierarchy

      GObject
       +----EShellView

## Implemented Interfaces

EShellView implements EExtensible.

## Properties

      "action"                   GtkRadioAction*       : Read / Write / Construct Only
      "page-num"                 gint                  : Read / Write
      "search-rule"              EFilterRule*          : Read / Write
      "shell-backend"            EShellBackend*        : Read
      "shell-content"            EShellContent*        : Read
      "shell-sidebar"            EShellSidebar*        : Read
      "shell-taskbar"            EShellTaskbar*        : Read
      "shell-window"             EShellWindow*         : Read / Write / Construct Only
      "state-key-file"           gpointer              : Read
      "title"                    gchar*                : Read / Write
      "view-id"                  gchar*                : Read / Write

## Signals

      "clear-search"                                   : Run Last
      "custom-search"                                  : Run Last
      "execute-search"                                 : Run First
      "toggled"                                        : Run First
      "update-actions"                                 : Run First

## Description

## Details

### struct EShellView

    struct EShellView;

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

### struct EShellViewClass

    struct EShellViewClass {
    	GObjectClass parent_class;

    	/* Initial switcher action values. */
    	const gchar *label;
    	const gchar *icon_name;

    	/* Base name of the UI definition file. */
    	const gchar *ui_definition;

    	/* GtkUIManager identifier for use with EPluginUI.
    	 * Usually "org.gnome.evolution.$(VIEW_NAME)". */
    	const gchar *ui_manager_id;

    	/* Search context.  Subclasses may override the type.
    	 * A unique instance is created for each subclass. */
    	GType search_context_type;
    	ERuleContext *search_context;

    	/* Widget path to the search options popup menu. */
    	const gchar *search_options;

    	/* Base name of the search rule definition file. */
    	const gchar *search_rules;

    	/* A unique instance is created for each subclass. */
    	GalViewCollection *view_collection;

    	/* This is set by the corresponding EShellBackend. */
    	EShellBackend *shell_backend;

    	/* Factory Methods */
    	GtkWidget * (*new_shell_content) (EShellView *shell_view);
    	GtkWidget * (*new_shell_sidebar) (EShellView *shell_view);
    	GtkWidget * (*new_shell_taskbar) (EShellView *shell_view);

    	/* Create, configure and pack a search bar widget. */
    	GtkWidget * (*construct_searchbar) (EShellView *shell_view);
    	gchar *		(*get_search_name) (EShellView *shell_view);

    	/* Signals */
    	void		(*toggled)		(EShellView *shell_view);
    	void		(*clear_search)		(EShellView *shell_view);
    	void		(*custom_search) (EShellView *shell_view,
    						 EFilterRule *custom_rule);
    	void		(*execute_search) (EShellView *shell_view);
    	void		(*update_actions) (EShellView *shell_view);
    };

EShellViewClass contains a number of important settings for subclasses.

GObjectClass `parent_class`; | The parent class structure.
const gchar *`label`; | The initial value for the switcher action's "label" property. See `e_shell_view_get_action()`.
const gchar *`icon_name`; | The initial value for the switcher action's "icon-name" property. See `e_shell_view_get_action()`.
const gchar *`ui_definition`; | Base name of the UI definintion file to add when the shell view is activated.
const gchar *`ui_manager_id`; | The GtkUIManager ID for EPluginUI. Plugins should use to this ID in their "eplug" files to add menu and toolbar items to the shell view.
GType `search_context_type`; | GType of the search context, which should be an instance of ERuleContextClass or a custom subclass.
ERuleContext *`search_context`; | A unique `search_context_type` instance is created automatically for each subclass and shared across all instances of that subclass.
const gchar *`search_options`; | Widget path in the UI definition to the search options popup menu. The menu gets shown when the user clicks the "find" icon in the search entry.
const gchar *`search_rules`; | Base name of the XML file containing predefined search rules for this shell view. The XML files are usually named something like `viewtypes.xml`.
GalViewCollection *`view_collection`; | A unique GalViewCollection instance is created for each subclass and shared across all instances of that subclass. That much is done automatically for subclasses, but subclasses are still responsible for adding the appropriate GalView factories to the view collection.
EShellBackend *`shell_backend`; | The corresponding EShellBackend for the shell view.
`new_shell_content` () | Factory method for the shell view's EShellContent. See `e_shell_view_get_shell_content()`.
`new_shell_sidebar` () | Factory method for the shell view's EShellSidebar. See `e_shell_view_get_shell_sidebar()`.
`new_shell_taskbar` () | Factory method for the shell view's EShellTaskbar. See `e_shell_view_get_shell_taskbar()`.
`construct_searchbar` () |
`get_search_name` () |
`toggled` () | Class method for the "toggled" signal. Subclasses should rarely need to override the default behavior.
`clear_search` () | Class method for the "clear-search" signal. The default method sets the "search-rule" to `NULL` and then emits the "execute-search" signal.
`custom_search` () | Class method for the "custom-search" signal. This is emitted prior to executing an advanced or saved search. The default method sets the "search-rule" property and then emits the "execute-search" signal.
`execute_search` () | Class method for the "execute-search" signal. There is no default behavior; subclasses should override this.
`update_actions` () | Class method for the "update-actions" signal. There is no default behavior; subclasses should override this.

### e_shell_view_get_name ()

    const gchar *       e_shell_view_get_name               (EShellView *shell_view);

Returns the view name for `shell_view`, which is also the name of the corresponding EShellBackend (see the `name` field in EShellBackendInfo).

`shell_view` : | an EShellView
Returns : | the view name for `shell_view`

### e_shell_view_get_action ()

    GtkAction *         e_shell_view_get_action             (EShellView *shell_view);

Returns the switcher action for `shell_view`.

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. The icon at the top of the sidebar also proxies the action. When `shell_view` is active, the action's icon becomes the EShellWindow icon.

`shell_view` : | an EShellView
Returns : | the switcher action for `shell_view`

### e_shell_view_get_title ()

    const gchar *       e_shell_view_get_title              (EShellView *shell_view);

Returns the title for `shell_view`. When `shell_view` is active, the shell view's title becomes the EShellWindow title.

`shell_view` : | an EShellView
Returns : | the title for `shell_view`

### e_shell_view_set_title ()

    void                e_shell_view_set_title              (EShellView *shell_view,
                                                             const gchar *title);

Sets the title for `shell_view`. When `shell_view` is active, the shell view's title becomes the EShellWindow title.

`shell_view` : | an EShellView
`title` : | a title for `shell_view`

### e_shell_view_get_view_id ()

    const gchar *       e_shell_view_get_view_id            (EShellView *shell_view);

Returns the ID of the currently selected GalView.

EShellView subclasses are responsible for keeping this property in sync with their GalViewInstance. EShellView itself just provides a place to store the view ID, and emits a "notify" signal when the property changes.

`shell_view` : | an EShellView
Returns : | the ID of the current GalView

### e_shell_view_set_view_id ()

    void                e_shell_view_set_view_id            (EShellView *shell_view,
                                                             const gchar *view_id);

Selects the GalView whose ID is equal to `view_id`.

EShellView subclasses are responsible for keeping this property in sync with their GalViewInstance. EShellView itself just provides a place to store the view ID, and emits a "notify" signal when the property changes.

`shell_view` : | an EShellView
`view_id` : | a GalView ID

### e_shell_view_is_active ()

    gboolean            e_shell_view_is_active              (EShellView *shell_view);

Returns `TRUE` if `shell_view` is active. That is, if it's currently visible in its EShellWindow. An EShellWindow can only display one shell view at a time.

Technically this just checks the "active" property of the shell view's switcher action. See `e_shell_view_get_action()`.

`shell_view` : | an EShellView
Returns : | `TRUE` if `shell_view` is active

### e_shell_view_get_page_num ()

    gint                e_shell_view_get_page_num           (EShellView *shell_view);

This function is only interesting to EShellWindow. It returns the GtkNotebook page number for `shell_view`. The rest of the application should have no need for this.

`shell_view` : | an EShellView
Returns : | the notebook page number for `shell_view`

### e_shell_view_set_page_num ()

    void                e_shell_view_set_page_num           (EShellView *shell_view,
                                                             gint page_num);

This function is only interesting to EShellWindow. It sets the GtkNotebook page number for `shell_view`. The rest of the application must never call this because it could mess up shell view switching.

`shell_view` : | an EShellView
`page_num` : | a notebook page number

### e_shell_view_get_searchbar ()

    GtkWidget *         e_shell_view_get_searchbar          (EShellView *shell_view);

`shell_view` : | an EShellView
Returns : | the searchbar widget for `shell_view`.

### e_shell_view_get_search_name ()

    gchar *             e_shell_view_get_search_name        (EShellView *shell_view);

Returns a newly-allocated string containing a suitable name for the current search criteria. This is used as the suggested name in the Save Search dialog. Free the returned string with `g_free()`.

`shell_view` : | an EShellView
Returns : | a name for the current search criteria

### e_shell_view_get_search_rule ()

    EFilterRule *       e_shell_view_get_search_rule        (EShellView *shell_view);

Returns the search criteria used to generate the current search results.

`shell_view` : | an EShellView
Returns : | the current search criteria

### e_shell_view_set_search_rule ()

    void                e_shell_view_set_search_rule        (EShellView *shell_view,
                                                             EFilterRule *search_rule);

Sets the search criteria used to generate the current search results. Note that this will not trigger a search. `e_shell_view_execute_search()` must be called explicitly.

`shell_view` : | an EShellView
`search_rule` : | an EFilterRule

### e_shell_view_get_search_query ()

    gchar *             e_shell_view_get_search_query       (EShellView *shell_view);

Converts the "search-rule" property to a newly-allocated S-expression string. If the "search-rule" property is `NULL` the function returns `NULL`.

`shell_view` : | an EShellView
Returns : | an S-expression string, or `NULL`

### e_shell_view_get_size_group ()

    GtkSizeGroup *      e_shell_view_get_size_group         (EShellView *shell_view);

Returns a GtkSizeGroup that EShellContent and EShellSidebar use to keep the search bar and sidebar banner vertically aligned. The rest of the application should have no need for this.

Note, this is only available during EShellView construction.

`shell_view` : | an EShellView
Returns : | a GtkSizeGroup for internal use

### e_shell_view_get_shell_backend ()

    EShellBackend *     e_shell_view_get_shell_backend      (EShellView *shell_view);

Returns the corresponding EShellBackend for `shell_view`.

`shell_view` : | an EShellView
Returns : | the corresponding EShellBackend for `shell_view`

### e_shell_view_get_shell_content ()

    EShellContent *     e_shell_view_get_shell_content      (EShellView *shell_view);

Returns the EShellContent instance for `shell_view`.

By default, EShellView creates a plain EShellContent during initialization. But EShellView subclasses can override the `new_shell_content` factory method in EShellViewClass to create a custom EShellContent.

`shell_view` : | an EShellView
Returns : | the EShellContent instance for `shell_view`

### e_shell_view_get_shell_sidebar ()

    EShellSidebar *     e_shell_view_get_shell_sidebar      (EShellView *shell_view);

Returns the EShellSidebar instance for `shell_view`.

By default, EShellView creates a plain EShellSidebar during initialization. But EShellView subclasses can override the `new_shell_sidebar` factory method in EShellViewClass to create a custom EShellSidebar.

`shell_view` : | an EShellView
Returns : | the EShellSidebar instance for `shell_view`

### e_shell_view_get_shell_taskbar ()

    EShellTaskbar *     e_shell_view_get_shell_taskbar      (EShellView *shell_view);

Returns the EShellTaskbar instance for `shell_view`.

By default, EShellView creates a plain EShellTaskbar during initialization. But EShellView subclasses can override the `new_shell_taskbar` factory method in EShellViewClass to create a custom EShellTaskbar.

`shell_view` : | an EShellView
Returns : | the EShellTaskbar instance for `shell_view`

### e_shell_view_get_shell_window ()

    EShellWindow *      e_shell_view_get_shell_window       (EShellView *shell_view);

Returns the EShellWindow to which `shell_view` belongs.

`shell_view` : | an EShellView
Returns : | the EShellWindow to which `shell_view` belongs

### e_shell_view_get_state_key_file ()

    GKeyFile *          e_shell_view_get_state_key_file     (EShellView *shell_view);

Returns the GKeyFile holding widget state data for `shell_view`.

`shell_view` : | an EShellView
Returns : | the GKeyFile for `shell_view`

### e_shell_view_set_state_dirty ()

    void                e_shell_view_set_state_dirty        (EShellView *shell_view);

Marks the widget state data as modified (or "dirty") and schedules it to be saved to disk after a short delay. The delay caps the frequency of saving to disk.

`shell_view` : | an EShellView

### e_shell_view_clear_search ()

    void                e_shell_view_clear_search           (EShellView *shell_view);

Emits the "clear-search" signal.

The default method sets the "search-rule" property to `NULL` and then emits the "execute-search" signal.

`shell_view` : | an EShellView

### e_shell_view_custom_search ()

    void                e_shell_view_custom_search          (EShellView *shell_view,
                                                             EFilterRule *custom_rule);

Emits the "custom-search" signal to indicate an advanced or saved search is about to be executed.

The default method sets the "search-rule" property to `custom_rule` and then emits the "execute-search" signal.

`shell_view` : | an EShellView
`custom_rule` : | an EFilterRule

### e_shell_view_execute_search ()

    void                e_shell_view_execute_search         (EShellView *shell_view);

Emits the "execute-search" signal.

EShellView subclasses should implement the `execute_search` method in EShellViewClass to execute a search based on the current search conditions.

`shell_view` : | an EShellView

### e_shell_view_block_execute_search ()

    void                e_shell_view_block_execute_search   (EShellView *shell_view);

Blocks `e_shell_view_execute_search()` in a way it does nothing. Pair function for this is `e_shell_view_unblock_execute_search()`.

`shell_view` : | an EShellView

### e_shell_view_unblock_execute_search ()

    void                e_shell_view_unblock_execute_search (EShellView *shell_view);

Unblocks previously blocked `e_shell_view_execute_search()` with function `e_shell_view_block_execute_search()`.

`shell_view` : | an EShellView

### e_shell_view_update_actions ()

    void                e_shell_view_update_actions         (EShellView *shell_view);

Emits the "update-actions" signal.

EShellView subclasses should implement the `update_actions` method in EShellViewClass to update the various GtkActions based on the current EShellSidebar and EShellContent selections. The "update-actions" signal is typically emitted just before showing a popup menu or just after the user selects an item in the shell view.

Emission can be blocked by `e_shell_view_block_update_actions()`.

`shell_view` : | an EShellView

### e_shell_view_block_update_actions ()

    void                e_shell_view_block_update_actions   (EShellView *shell_view);

Block emission of "update-actions" signal through `e_shell_view_update_actions()`. The emission si blocked until `e_shell_view_unblock_update_actions()` is called same times as this function.

`shell_view` : | an EShellView

### e_shell_view_unblock_update_actions ()

    void                e_shell_view_unblock_update_actions (EShellView *shell_view);

Unblock emission of "update-actions" signal through `e_shell_view_update_actions()`, previously blocked by function `e_shell_view_block_update_actions()`.

`shell_view` : | an EShellView

### e_shell_view_show_popup_menu ()

    GtkWidget *         e_shell_view_show_popup_menu        (EShellView *shell_view,
                                                             const gchar *widget_path,
                                                             GdkEventButton *event);

Displays a context-sensitive (or "popup") menu that is described in the UI definition loaded into `shell_view`'s user interface manager. The menu will be shown at the current mouse cursor position.

The "update-actions" signal is emitted just prior to showing the menu to give `shell_view` and any plugins that extend `shell_view` a chance to update the menu's actions.

`shell_view` : | an EShellView
`widget_path` : | path in the UI definition
`event` : | a GdkEventButton
Returns : | the popup menu being displayed

### e_shell_view_new_view_instance ()

    GalViewInstance *   e_shell_view_new_view_instance      (EShellView *shell_view,
                                                             const gchar *instance_id);

Creates a new GalViewInstance and configures it to keep `shell_view`'s "view-id" property up-to-date.

`shell_view` : | an EShellView
`instance_id` : | a name for the GalViewInstance
Returns : | a new GalViewInstance

## Property Details

### The `"action"` property

      "action"                   GtkRadioAction*       : Read / Write / Construct Only

The GtkRadioAction registered with EShellSwitcher.

### The `"page-num"` property

      "page-num"                 gint                  : Read / Write

The GtkNotebook page number of the shell view.

Allowed values: >= -1

Default value: -1

### The `"search-rule"` property

      "search-rule"              EFilterRule*          : Read / Write

Criteria for the current search results.

### The `"shell-backend"` property

      "shell-backend"            EShellBackend*        : Read

The EShellBackend for this shell view.

### The `"shell-content"` property

      "shell-content"            EShellContent*        : Read

The content widget appears in an EShellWindow's right pane.

### The `"shell-sidebar"` property

      "shell-sidebar"            EShellSidebar*        : Read

The sidebar widget appears in an EShellWindow's left pane.

### The `"shell-taskbar"` property

      "shell-taskbar"            EShellTaskbar*        : Read

The taskbar widget appears at the bottom of an EShellWindow.

### The `"shell-window"` property

      "shell-window"             EShellWindow*         : Read / Write / Construct Only

The EShellWindow to which the shell view belongs.

### The `"state-key-file"` property

      "state-key-file"           gpointer              : Read

The GKeyFile holding widget state data.

### The `"title"` property

      "title"                    gchar*                : Read / Write

The title of the shell view. Also serves as the EShellWindow title when the shell view is active.

Default value: NULL

### The `"view-id"` property

      "view-id"                  gchar*                : Read / Write

The current GalView ID.

Default value: NULL

## Signal Details

### The `"clear-search"` signal

    void                user_function                      (EShellView *shell_view,
                                                            gpointer    user_data)       : Run Last

Clears the current search. See `e_shell_view_clear_search()` for details.

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

### The `"custom-search"` signal

    void                user_function                      (EShellView  *shell_view,
                                                            EFilterRule *custom_rule,
                                                            gpointer     user_data)        : Run Last

Emitted when an advanced or saved search is about to be executed. See `e_shell_view_custom_search()` for details.

`shell_view` : | the EShellView which emitted the signal
`custom_rule` : | criteria for the custom search
`user_data` : | user data set when the signal handler was connected.

### The `"execute-search"` signal

    void                user_function                      (EShellView *shell_view,
                                                            gpointer    user_data)       : Run First

EShellView subclasses should override the `execute_search` method in EShellViewClass to execute the current search conditions.

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

### The `"toggled"` signal

    void                user_function                      (EShellView *shell_view,
                                                            gpointer    user_data)       : Run First

Emitted when `shell_view` is activated or deactivated. Use `e_shell_view_is_active()` to find out which event has occurred. The shell view being deactivated is always notified before the shell view being activated.

By default, EShellView adds the UI definition file given in the `ui_definition` field of EShellViewClass on activation, and removes the UI definition on deactivation.

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

### The `"update-actions"` signal

    void                user_function                      (EShellView *shell_view,
                                                            gpointer    user_data)       : Run First

EShellView subclasses should override the `update_actions` method in EShellViewClass to update sensitivities, labels, or any other aspect of the GtkActions they have registered.

Plugins can also connect to this signal to be notified when to update their own GtkActions.

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