Evolution Shell Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
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
); 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
); gboolean e_shell_view_is_execute_search_blocked (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
,GdkEvent *button_event
); GalViewInstance * e_shell_view_new_view_instance (EShellView *shell_view
,const gchar *instance_id
); void e_shell_view_write_source (EShellView *shell_view
,ESource *source
); void e_shell_view_remove_source (EShellView *shell_view
,ESource *source
); void e_shell_view_remote_delete_source (EShellView *shell_view
,ESource *source
);
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
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); GtkWidget * (*new_shell_searchbar) (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.
The parent class structure. | |
The initial value for the switcher action's
"label" property. See
e_shell_view_get_action() . |
|
The initial value for the switcher action's
"icon-name" property. See
e_shell_view_get_action() . |
|
Base name of the UI definintion file to add when the shell view is activated. | |
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 of the search context, which should be an instance of ERuleContextClass or a custom subclass. | |
ERuleContext * |
A unique search_context_type instance is created
automatically for each subclass and shared across
all instances of that subclass. |
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. | |
Base name of the XML file containing predefined search rules for this shell view. The XML files are usually named something like <filename> <emphasis>view</emphasis>types.xml</filename>. | |
GalViewCollection * |
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 * |
The corresponding EShellBackend for the shell view. |
Factory method for the shell view's EShellContent.
See e_shell_view_get_shell_content() . |
|
Factory method for the shell view's EShellSidebar.
See e_shell_view_get_shell_sidebar() . |
|
Factory method for the shell view's EShellTaskbar.
See e_shell_view_get_shell_taskbar() . |
|
Factory method for the shell view's EShellSearchbar.
See e_shell_view_get_searchbar() . |
|
Class method to create, configure and pack a search bar widget. The search bar differs in normal shell mode versus "express" mode. | |
Class method to obtain a suitable name for the current search criteria. Subclasses should rarely need to override the default behavior. | |
Class method for the "toggled" signal. Subclasses should rarely need to override the default behavior. | |
Class method for the "clear-search"
signal. The default method sets the
"search-rule" to NULL and then emits
the "execute-search" signal. |
|
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. | |
Class method for the "execute-search" signal. There is no default behavior; subclasses should override this. | |
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 <structfield>name</structfield>
field in EShellBackendInfo).
|
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.
|
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.
|
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.
|
an EShellView |
|
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.
|
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.
|
an EShellView |
|
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()
.
|
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.
|
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.
|
an EShellView |
|
a notebook page number |
e_shell_view_get_searchbar ()
GtkWidget * e_shell_view_get_searchbar (EShellView *shell_view
);
Returns the searchbar widget for 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()
.
|
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.
|
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.
|
an EShellView |
|
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
.
|
an EShellView |
Returns : |
an S-expression string, or NULL
|
e_shell_view_get_shell_backend ()
EShellBackend * e_shell_view_get_shell_backend (EShellView *shell_view
);
Returns the corresponding EShellBackend for 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 <structfield>new_shell_content</structfield> factory method in EShellViewClass to create a custom EShellContent.
|
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 <structfield>new_shell_sidebar</structfield> factory method in EShellViewClass to create a custom EShellSidebar.
|
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 <structfield>new_shell_taskbar</structfield> factory method in EShellViewClass to create a custom EShellTaskbar.
|
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.
|
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
.
|
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.
|
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.
|
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.
|
an EShellView |
|
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 <structfield>execute_search</structfield> method in EShellViewClass to execute a search based on the current search conditions.
|
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()
.
|
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()
.
|
an EShellView |
e_shell_view_is_execute_search_blocked ()
gboolean e_shell_view_is_execute_search_blocked
(EShellView *shell_view
);
Returns whether e_shell_view_execute_search()
is blocked as a result
of previous e_shell_view_block_execute_search()
calls.
|
an EShellView |
Returns : |
TRUE if e_shell_view_execute_search() is blocked |
e_shell_view_update_actions ()
void e_shell_view_update_actions (EShellView *shell_view
);
Emits the "update-actions" signal.
EShellView subclasses should implement the <structfield>update_actions</structfield> method in EShellViewClass to update the various GtkAction<!-- -->s 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()
.
|
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.
|
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()
.
|
an EShellView |
e_shell_view_show_popup_menu ()
GtkWidget * e_shell_view_show_popup_menu (EShellView *shell_view
,const gchar *widget_path
,GdkEvent *button_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.
|
an EShellView |
|
path in the UI definition |
|
a GdkEvent, or NULL
|
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.
|
an EShellView |
|
a name for the GalViewInstance |
Returns : |
a new GalViewInstance |
e_shell_view_write_source ()
void e_shell_view_write_source (EShellView *shell_view
,ESource *source
);
Submits the current contents of source
to the D-Bus service to be
written to disk and broadcast to other clients.
This function does not block: shell_view
will dispatch the operation
asynchronously and handle any errors.
|
an EShellView |
|
an ESource |
e_shell_view_remove_source ()
void e_shell_view_remove_source (EShellView *shell_view
,ESource *source
);
Requests the D-Bus service to delete the key files for source
and all of
its descendants and broadcast their removal to all clients.
This function does not block: shell_view
will dispatch the operation
asynchronously and handle any errors.
|
an EShellView |
|
the ESource to be removed |
e_shell_view_remote_delete_source ()
void e_shell_view_remote_delete_source (EShellView *shell_view
,ESource *source
);
Deletes the resource represented by source
from a remote server.
The source
must be "remote-deletable". This will also delete
the key file for source
and broadcast its removal to all clients,
similar to e_shell_view_remove_source()
.
This function does not block; shell_view
will dispatch the operation
asynchronously and handle any errors.
|
an EShellView |
|
an ESource |
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: >= G_MAXULONG
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
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.
|
the EShellView which emitted the signal |
|
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.
|
the EShellView which emitted the signal |
|
criteria for the custom search |
|
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 <structfield>execute_search</structfield> method in EShellViewClass to execute the current search conditions.
|
the EShellView which emitted the signal |
|
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 <structfield>ui_definition</structfield> field of EShellViewClass on activation, and removes the UI definition on deactivation.
|
the EShellView which emitted the signal |
|
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 <structfield>update_actions</structfield> method in EShellViewClass to update sensitivities, labels, or any other aspect of the GtkAction<!-- -->s they have registered.
Plugins can also connect to this signal to be notified when to update their own GtkAction<!-- -->s.
|
the EShellView which emitted the signal |
|
user data set when the signal handler was connected. |