Evolution Shell Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
Synopsis
#include <shell/e-shell.h> struct EShell; EShell * e_shell_get_default (void
); void e_shell_load_modules (EShell *shell
); GList * e_shell_get_shell_backends (EShell *shell
); const gchar * e_shell_get_canonical_name (EShell *shell
,const gchar *name
); EShellBackend * e_shell_get_backend_by_name (EShell *shell
,const gchar *name
); EShellBackend * e_shell_get_backend_by_scheme (EShell *shell
,const gchar *scheme
); EClientCache * e_shell_get_client_cache (EShell *shell
); EShellSettings * e_shell_get_shell_settings (EShell *shell
); ESourceRegistry * e_shell_get_registry (EShell *shell
); GtkWidget * e_shell_create_shell_window (EShell *shell
,const gchar *view_name
); guint e_shell_handle_uris (EShell *shell
,const gchar * const *uris
,gboolean do_import
); void e_shell_submit_alert (EShell *shell
,EAlert *alert
); GtkWindow * e_shell_get_active_window (EShell *shell
); gboolean e_shell_get_meego_mode (EShell *shell
); gboolean e_shell_get_express_mode (EShell *shell
); gboolean e_shell_get_small_screen_mode (EShell *shell
); const gchar * e_shell_get_module_directory (EShell *shell
); gboolean e_shell_get_network_available (EShell *shell
); void e_shell_set_network_available (EShell *shell
,gboolean network_available
); void e_shell_lock_network_available (EShell *shell
); gboolean e_shell_get_online (EShell *shell
); void e_shell_set_online (EShell *shell
,gboolean online
); GtkWidget * e_shell_get_preferences_window (EShell *shell
); void e_shell_event (EShell *shell
,const gchar *event_name
,gpointer event_data
); enum EShellQuitReason; gboolean e_shell_quit (EShell *shell
,EShellQuitReason reason
); void e_shell_cancel_quit (EShell *shell
); void e_shell_adapt_window_size (EShell *shell
,GtkWindow *window
); void e_shell_set_startup_view (EShell *shell
,const gchar *view
); const gchar * e_shell_get_startup_view (EShell *shell
); gboolean e_shell_migrate_attempt (EShell *shell
); void e_shell_detect_meego (gboolean *is_meego
,gboolean *small_screen
);
Properties
"client-cache" EClientCache* : Read "express-mode" gboolean : Read / Write / Construct Only "geometry" gchar* : Write / Construct Only "meego-mode" gboolean : Read / Write / Construct Only "module-directory" gchar* : Read / Write / Construct Only "network-available" gboolean : Read / Write "online" gboolean : Read / Write / Construct "registry" ESourceRegistry* : Read "shell-settings" EShellSettings* : Read "small-screen-mode" gboolean : Read / Write / Construct Only
Signals
"event" :Action
"handle-uri" :Action
"prepare-for-offline" :Run First
"prepare-for-online" :Run First
"prepare-for-quit" :Run First
"quit-requested" :Run First
Details
struct EShell
struct EShell;
Contains only private data that should be read and manipulated using the functions below.
e_shell_get_default ()
EShell * e_shell_get_default (void
);
Returns the EShell created by <function>main()
</function>.
Try to obtain the EShell from elsewhere if you can. This function is intended as a temporary workaround for when that proves difficult.
Returns : |
the EShell singleton |
e_shell_load_modules ()
void e_shell_load_modules (EShell *shell
);
Loads all installed modules and performs some internal bookkeeping. This function should be called after creating the EShell instance but before initiating migration or starting the main loop.
|
an EShell |
e_shell_get_shell_backends ()
GList * e_shell_get_shell_backends (EShell *shell
);
Returns a list of loaded EShellBackend instances. The list is
owned by shell
and should not be modified or freed.
|
an EShell |
Returns : |
a list of loaded EShellBackend instances |
e_shell_get_canonical_name ()
const gchar * e_shell_get_canonical_name (EShell *shell
,const gchar *name
);
Returns the canonical name for the EShellBackend whose name or alias
is name
.
|
an EShell |
|
the name or alias of an EShellBackend |
Returns : |
the canonical EShellBackend name |
e_shell_get_backend_by_name ()
EShellBackend * e_shell_get_backend_by_name (EShell *shell
,const gchar *name
);
Returns the corresponding EShellBackend for the given name or alias,
or NULL
if name
is not recognized.
|
an EShell |
|
the name or alias of an EShellBackend |
Returns : |
the EShellBackend named name , or NULL
|
e_shell_get_backend_by_scheme ()
EShellBackend * e_shell_get_backend_by_scheme (EShell *shell
,const gchar *scheme
);
Returns the EShellBackend that implements the given URI scheme,
or NULL
if scheme
is not recognized.
|
an EShell |
|
a URI scheme |
Returns : |
the EShellBackend that implements scheme , or NULL
|
e_shell_get_client_cache ()
EClientCache * e_shell_get_client_cache (EShell *shell
);
Returns the EClientCache instance for shell
.
|
an EShell |
Returns : |
the EClientCache instance for shell
|
e_shell_get_shell_settings ()
EShellSettings * e_shell_get_shell_settings (EShell *shell
);
Returns the EShellSettings instance for shell
.
|
an EShell |
Returns : |
the EShellSettings instance for shell
|
e_shell_get_registry ()
ESourceRegistry * e_shell_get_registry (EShell *shell
);
Returns the shell's ESourceRegistry which holds all ESource instances.
|
an EShell |
Returns : |
the ESourceRegistry |
e_shell_create_shell_window ()
GtkWidget * e_shell_create_shell_window (EShell *shell
,const gchar *view_name
);
Creates a new EShellWindow. Use this function instead of
e_shell_window_new()
so that shell
can properly configure
the window.
|
an EShell |
|
name of the initial shell view, or NULL
|
Returns : |
a new EShellWindow |
e_shell_handle_uris ()
guint e_shell_handle_uris (EShell *shell
,const gchar * const *uris
,gboolean do_import
);
Emits the "handle-uri" signal for each URI.
|
an EShell |
|
NULL -terminated list of URIs |
|
request an import of the URIs |
Returns : |
the number of URIs successfully handled |
e_shell_submit_alert ()
void e_shell_submit_alert (EShell *shell
,EAlert *alert
);
Broadcasts alert
to all EShellWindow<!-- -->s. This should only
be used for application-wide alerts such as a network outage. Submit
view-specific alerts to the appropriate EShellContent instance.
e_shell_get_active_window ()
GtkWindow * e_shell_get_active_window (EShell *shell
);
Returns the most recently focused watched window, according to
gtk_application_get_windows()
. Convenient for finding a parent
for a transient window.
Note the returned window is not necessarily an EShellWindow.
|
an EShell or NULL to use the default shell |
Returns : |
the most recently focused watched window |
e_shell_get_meego_mode ()
gboolean e_shell_get_meego_mode (EShell *shell
);
Returns TRUE
if Evolution is in MeeGo mode.
|
an EShell |
Returns : |
TRUE if Evolution is in MeeGo mode |
e_shell_get_express_mode ()
gboolean e_shell_get_express_mode (EShell *shell
);
Returns TRUE
if Evolution is in express mode.
|
an EShell |
Returns : |
TRUE if Evolution is in express mode |
e_shell_get_small_screen_mode ()
gboolean e_shell_get_small_screen_mode (EShell *shell
);
Returns TRUE
if Evolution is in small (netbook) screen mode.
|
an EShell |
Returns : |
TRUE if Evolution is in small screen mode |
e_shell_get_module_directory ()
const gchar * e_shell_get_module_directory (EShell *shell
);
Returns the directory from which EModule<!-- -->s were loaded.
e_shell_get_network_available ()
gboolean e_shell_get_network_available (EShell *shell
);
Returns TRUE
if a network is available.
|
an EShell |
Returns : |
TRUE if a network is available |
e_shell_set_network_available ()
void e_shell_set_network_available (EShell *shell
,gboolean network_available
);
Sets whether a network is available. This is usually called in
response to a status change signal from NetworkManager. If the
network becomes unavailable while "online" is TRUE
, the
shell
will force "online" to FALSE
until the network
becomes available again.
|
an EShell |
|
whether a network is available |
e_shell_lock_network_available ()
void e_shell_lock_network_available (EShell *shell
);
Locks the value of "network-available" to TRUE
. Further
attempts to set the property will be ignored.
This is used for the --force-online command-line option, which is intended to override the network availability status as reported by NetworkManager or other network monitoring software.
|
an EShell |
e_shell_get_online ()
gboolean e_shell_get_online (EShell *shell
);
Returns TRUE
if Evolution is online, FALSE
if Evolution is offline.
Evolution may be offline because the user elected to work offline, or
because the network has become unavailable.
|
an EShell |
Returns : |
TRUE if Evolution is online |
e_shell_set_online ()
void e_shell_set_online (EShell *shell
,gboolean online
);
Asynchronously places Evolution in online or offline mode.
|
an EShell |
|
TRUE to go online, FALSE to go offline |
e_shell_get_preferences_window ()
GtkWidget * e_shell_get_preferences_window (EShell *shell
);
Returns the Evolution Preferences window.
|
an EShell |
Returns : |
the preferences window |
e_shell_event ()
void e_shell_event (EShell *shell
,const gchar *event_name
,gpointer event_data
);
The "event" signal acts as a cheap mechanism for broadcasting
events to the rest of the application, such as new mail arriving. The
event_name
is used as the signal detail, and event_data
may point to
an object or data structure associated with the event.
|
an EShell |
|
the name of the event |
|
data associated with the event |
enum EShellQuitReason
typedef enum { E_SHELL_QUIT_ACTION, E_SHELL_QUIT_LAST_WINDOW, E_SHELL_QUIT_OPTION, E_SHELL_QUIT_REMOTE_REQUEST, E_SHELL_QUIT_SESSION_REQUEST } EShellQuitReason;
These values are passed in the "quit-requested" signal to indicate why the shell is requesting to shut down.
E_SHELL_WINDOW_ACTION_QUIT was activated.
|
|
The last watched window has been destroyed. | |
The program was invoked with --quit. Extensions will never see this value because they are not loaded when --quit is given. | |
Another Evolution process requested we quit. | |
The desktop session requested we quit. |
e_shell_quit ()
gboolean e_shell_quit (EShell *shell
,EShellQuitReason reason
);
Requests an application shutdown. This happens in two phases: the first is synchronous, the second is asynchronous.
In the first phase, the shell
emits a "quit-requested" signal
to potentially give the user a chance to cancel shutdown. If the user
cancels shutdown, the function returns FALSE
. Otherwise it proceeds
into the second phase.
In the second phase, the shell
emits a "prepare-for-quit"
signal and immediately returns TRUE
. Signal handlers may delay the
actual application shutdown while they clean up resources, but there
is no way to cancel shutdown at this point.
Consult the documentation for these two signals for details on how to handle them.
|
an EShell |
|
the reason for quitting |
Returns : |
TRUE if shutdown is underway, FALSE if it was cancelled |
e_shell_cancel_quit ()
void e_shell_cancel_quit (EShell *shell
);
This function may only be called from "quit-requested" signal handlers to prevent Evolution from quitting. Calling this will stop further emission of the "quit-requested" signal.
Note: This function has no effect during a "prepare-for-quit" signal emission.
|
an EShell |
e_shell_adapt_window_size ()
void e_shell_adapt_window_size (EShell *shell
,GtkWindow *window
);
This is used to adapt to window's size to be optimal for the platform. The shell settings are used to determine if a window should be set to full screen etc.
This method is best called when the widget is realized on a given screen.
|
an EShell |
|
a GtkWindow to adapt to full-screen |
Property Details
The "express-mode"
property
"express-mode" gboolean : Read / Write / Construct Only
Express mode alters Evolution's user interface to be more usable on devices with small screens.
Default value: FALSE
The "geometry"
property
"geometry" gchar* : Write / Construct Only
User-specified initial window geometry string to apply to the first EShellWindow created.
Default value: NULL
The "meego-mode"
property
"meego-mode" gboolean : Read / Write / Construct Only
Whether meego mode is enabled.
Default value: FALSE
The "module-directory"
property
"module-directory" gchar* : Read / Write / Construct Only
The directory from which to load EModule<!-- -->s.
Default value: NULL
The "network-available"
property
"network-available" gboolean : Read / Write
Whether the network is available.
Default value: TRUE
The "online"
property
"online" gboolean : Read / Write / Construct
Whether the shell is online.
Default value: FALSE
The "registry"
property
"registry" ESourceRegistry* : Read
The ESourceRegistry manages ESource instances.
Signal Details
The "event"
signal
void user_function (EShell *shell,
gpointer event_data,
gpointer user_data) : Action
This signal is used to broadcast custom events to the entire
application. The nature of event_data
depends on the event
being broadcast. The signal's detail denotes the event.
|
the EShell which emitted the signal |
|
data associated with the event |
|
user data set when the signal handler was connected. |
The "handle-uri"
signal
gboolean user_function (EShell *shell,
gchar *uri,
gpointer user_data) : Action
Emitted when shell
receives a URI to be handled, usually by
way of a command-line argument. An EShellBackend should listen
for this signal and try to handle the URI, usually by opening an
editor window for the identified resource.
|
the EShell which emitted the signal |
|
the URI to be handled |
|
user data set when the signal handler was connected. |
Returns : |
TRUE if the URI could be handled, FALSE otherwise |
The "prepare-for-offline"
signal
void user_function (EShell *shell,
EActivity *activity,
gpointer user_data) : Run First
Emitted when the user elects to work offline. An EShellBackend should listen for this signal and make preparations for working in offline mode.
If preparations for working offline cannot immediately be
completed (such as when synchronizing with a remote server),
the EShellBackend should reference the activity
until
preparations are complete, and then unreference the activity
.
This will delay Evolution from actually going to offline mode
until all backends have unreferenced activity
.
The "prepare-for-online"
signal
void user_function (EShell *shell,
EActivity *activity,
gpointer user_data) : Run First
Emitted when the user elects to work online. An EShellBackend should listen for this signal and make preparations for working in online mode.
If preparations for working online cannot immediately be
completed (such as when re-connecting to a remote server), the
EShellBackend should reference the activity
until preparations
are complete, and then unreference the activity
. This will
delay Evolution from actually going to online mode until all
backends have unreferenced activity
.
The "prepare-for-quit"
signal
void user_function (EShell *shell,
EActivity *activity,
gpointer user_data) : Run First
Emitted when the user elects to quit the application, after "quit-requested". An EShellBackend should listen for this signal and make preparations for shutting down.
If preparations for shutting down cannot immediately be completed
(such as when there are uncompleted network operations), the
EShellBackend should reference the activity
until preparations
are complete, and then unreference the activity
. This will
delay Evolution from actually shutting down until all backends
have unreferenced activity
.
The "quit-requested"
signal
void user_function (EShell *shell,
EShellQuitReason reason,
gpointer user_data) : Run First
Emitted when the user elects to quit the application, before "prepare-for-quit".
EShellBackend<!-- -->s and editor windows can listen for
this signal to prompt the user to save changes or finish
scheduled operations immediately (such as sending mail in
Outbox). If the user elects to cancel, the signal handler
should call e_shell_cancel_quit()
to abort the quit.
|
the EShell which emitted the signal |
|
the reason for quitting |
|
user data set when the signal handler was connected. |