EMsgComposer: Evolution Mail Composer Reference Manual

EMsgComposer

Functions

void	e_msg_composer_new ()
EMsgComposer *	e_msg_composer_new_finish ()
void	e_msg_composer_setup_with_message ()
void	e_msg_composer_setup_from_url ()
void	e_msg_composer_setup_redirect ()
EHTMLEditor *	e_msg_composer_get_editor ()
EFocusTracker *	e_msg_composer_get_focus_tracker ()
CamelSession *	e_msg_composer_ref_session ()
EShell *	e_msg_composer_get_shell ()
EContentEditorContentHash *	e_msg_composer_get_content_hash ()
void	e_msg_composer_send ()
void	e_msg_composer_save_to_drafts ()
void	e_msg_composer_save_to_outbox ()
void	e_msg_composer_print ()
void	e_msg_composer_set_body_text ()
void	e_msg_composer_set_body ()
void	e_msg_composer_add_header ()
void	e_msg_composer_set_header ()
const gchar *	e_msg_composer_get_header ()
void	e_msg_composer_remove_header ()
void	e_msg_composer_set_draft_headers ()
void	e_msg_composer_set_source_headers ()
void	e_msg_composer_attach ()
void	e_msg_composer_set_alternative_body ()
void	e_msg_composer_get_message ()
CamelMimeMessage *	e_msg_composer_get_message_finish ()
void	e_msg_composer_get_message_print ()
CamelMimeMessage *	e_msg_composer_get_message_print_finish ()
void	e_msg_composer_get_message_draft ()
CamelMimeMessage *	e_msg_composer_get_message_draft_finish ()
CamelInternetAddress *	e_msg_composer_get_from ()
CamelInternetAddress *	e_msg_composer_get_reply_to ()
void	e_msg_composer_add_message_attachments ()
void	e_msg_composer_add_attachments_from_part_list ()
void	e_msg_composer_check_inline_attachments ()
void	e_msg_composer_request_close ()
gboolean	e_msg_composer_can_close ()
EComposerHeaderTable *	e_msg_composer_get_header_table ()
EAttachmentView *	e_msg_composer_get_attachment_view ()
GByteArray *	e_msg_composer_get_raw_message_text_without_signature ()
GByteArray *	e_msg_composer_get_raw_message_text ()
gboolean	e_msg_composer_is_exiting ()
void	e_save_spell_languages ()
void	e_msg_composer_save_focused_widget ()
void	e_msg_composer_restore_focus_on_composer ()
gboolean	e_msg_composer_is_busy ()
gboolean	e_msg_composer_is_soft_busy ()
gboolean	e_msg_composer_get_is_reply_or_forward ()
void	e_msg_composer_set_is_reply_or_forward ()
void	e_msg_composer_check_autocrypt ()
void	e_msg_composer_set_is_imip ()
gboolean	e_msg_composer_get_is_imip ()

Properties

gboolean	busy	Read
EHTMLEditor *	editor	Read / Write / Construct Only
EFocusTracker *	focus-tracker	Read
gboolean	is-reply-or-forward	Read / Write
EShell *	shell	Read / Write / Construct Only
gboolean	soft-busy	Read

Signals

void	before-destroy	Run Last
gboolean	presend	Run Last
void	print	Run Last
void	save-to-drafts	Run Last
void	save-to-outbox	Run Last
void	send	Run Last

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ╰── GtkBin
                    ╰── GtkWindow
                        ╰── EMsgComposer

Description

Functions

e_msg_composer_new ()

void
e_msg_composer_new (EShell *shell,
                    GAsyncReadyCallback callback,
                    gpointer user_data);

Asynchronously creates an EMsgComposer. The operation is finished with e_msg_composer_new_finish() called from within the callback .

Parameters

shell	an EShell
callback	called when the composer is ready
user_data	user data passed to `callback`

Since: 3.22

e_msg_composer_new_finish ()

EMsgComposer *
e_msg_composer_new_finish (GAsyncResult *result,
                           GError **error);

Finishes call of e_msg_composer_new().

Parameters

result	a GAsyncResult provided by the callback from `e_msg_composer_new()`
error	optional GError for errors

Since: 3.22

e_msg_composer_setup_with_message ()

void
e_msg_composer_setup_with_message (EMsgComposer *composer,
                                   CamelMimeMessage *message,
                                   gboolean keep_signature,
                                   const gchar *override_identity_uid,
                                   const gchar *override_alias_name,
                                   const gchar *override_alias_address,
                                   GCancellable *cancellable);

Sets up the message composer with a specific message .

Note: Designed to work only for messages constructed using Evolution.

Parameters

composer	an EMsgComposer
message	The message to use as the source
keep_signature	Keep message signature, if any
override_identity_uid	Optional identity UID to use, or `NULL`.	[allow none]
override_alias_name	an alias name to use together with the override_identity_uid, or `NULL`.	[nullable]
override_alias_address	an alias address to use together with the override_identity_uid, or `NULL`.	[nullable]
cancellable	optional GCancellable object, or `NULL`

Since: 3.22

e_msg_composer_setup_from_url ()

void
e_msg_composer_setup_from_url (EMsgComposer *composer,
                               const gchar *url);

Sets up the message composer content as defined by the provided URL.

Parameters

composer	an EMsgComposer
url	a mailto URL

Since: 3.22

e_msg_composer_setup_redirect ()

void
e_msg_composer_setup_redirect (EMsgComposer *composer,
                               CamelMimeMessage *message,
                               const gchar *identity_uid,
                               const gchar *alias_name,
                               const gchar *alias_address,
                               GCancellable *cancellable);

Sets up the message composer as a redirect of the message .

Parameters

composer	an EMsgComposer
message	The message to use as the source
identity_uid	an identity UID to use, if any.	[nullable]
alias_name	an alias name to use together with the identity_uid, or `NULL`.	[nullable]
alias_address	an alias address to use together with the identity_uid, or `NULL`.	[nullable]
cancellable	an optional GCancellable

Since: 3.22

e_msg_composer_get_editor ()

EHTMLEditor *
e_msg_composer_get_editor (EMsgComposer *composer);

Returns composer 's internal EHTMLEditor instance.

Parameters

composer

an EMsgComposer

Returns

an EHTMLEditor

e_msg_composer_get_focus_tracker ()

EFocusTracker *
e_msg_composer_get_focus_tracker (EMsgComposer *composer);

e_msg_composer_ref_session ()

CamelSession *
e_msg_composer_ref_session (EMsgComposer *composer);

Returns the mail module's global CamelSession instance. Calling this function will load the mail module if it isn't already loaded.

The returned CamelSession is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

Parameters

composer

an EMsgComposer

Returns

the mail module's CamelSession

e_msg_composer_get_shell ()

EShell *
e_msg_composer_get_shell (EMsgComposer *composer);

Returns the EShell that was passed to e_msg_composer_new().

Parameters

composer

an EMsgComposer

Returns

the EShell

e_msg_composer_get_content_hash ()

EContentEditorContentHash *
e_msg_composer_get_content_hash (EMsgComposer *composer);

Returns current EContentEditorContentHash with content of the composer. It's valid, and available, only during operations/signals, which construct message from the composer content. The composer precaches the content, thus it can be accessed in a synchronous way (in constrast to EContentEditor, which allows getting the content only asynchronously). The content hash is owned by the composer and it is freed as soon as the respective operation is finished.

Parameters

composer

an EMsgComposer

Returns

an EContentEditorContentHash with current content data, or NULL, when it is not loaded.

[transfer none][nullable]

Since: 3.38

e_msg_composer_send ()

void
e_msg_composer_send (EMsgComposer *composer);

Send the message in composer .

Parameters

composer

an EMsgComposer

e_msg_composer_save_to_drafts ()

void
e_msg_composer_save_to_drafts (EMsgComposer *composer);

Save the message in composer to the selected account's Drafts folder.

Parameters

composer

an EMsgComposer

e_msg_composer_save_to_outbox ()

void
e_msg_composer_save_to_outbox (EMsgComposer *composer);

Save the message in composer to the local Outbox folder.

Parameters

composer

an EMsgComposer

e_msg_composer_print ()

void
e_msg_composer_print (EMsgComposer *composer,
                      GtkPrintOperationAction print_action);

Print the message in composer .

Parameters

composer	an EMsgComposer
print_action	the print action to start

e_msg_composer_set_body_text ()

void
e_msg_composer_set_body_text (EMsgComposer *composer,
                              const gchar *text,
                              gboolean update_signature);

Loads the given HTML text into the editor.

Parameters

composer	a composer object
text	the HTML text to initialize the editor with
update_signature	whether update signature in the text after setting it; Might be usually called with TRUE.

e_msg_composer_set_body ()

void
e_msg_composer_set_body (EMsgComposer *composer,
                         const gchar *body,
                         const gchar *mime_type);

Loads the given data into the composer as the message body.

Parameters

composer	a composer object
body	the data to initialize the composer with
mime_type	the MIME type of data

e_msg_composer_add_header ()

void
e_msg_composer_add_header (EMsgComposer *composer,
                           const gchar *name,
                           const gchar *value);

Adds a new custom header created from name and value . The header is not shown in the user interface but will be added to the resulting MIME message when sending or saving.

Parameters

composer	an EMsgComposer
name	the header's name
value	the header's value

e_msg_composer_set_header ()

void
e_msg_composer_set_header (EMsgComposer *composer,
                           const gchar *name,
                           const gchar *value);

Replaces all custom headers matching name that were added with e_msg_composer_add_header() or e_msg_composer_set_header(), with a new custom header created from name and value . The header is not shown in the user interface but will be added to the resulting MIME message when sending or saving.

Parameters

composer	an EMsgComposer
name	the header's name
value	the header's value

e_msg_composer_get_header ()

const gchar *
e_msg_composer_get_header (EMsgComposer *composer,
                           const gchar *name,
                           gint index);

Returns header value of the header named name previously added by e_msg_composer_add_header() or set by e_msg_composer_set_header(). The index is which header index to return. Returns NULL on error or when the given index of the header couldn't be found.

Parameters

composer	an EMsgComposer
name	the header's name
index	index of the header, 0-based

Returns

stored header value or NULL, if couldn't be found.

Since: 3.20

e_msg_composer_remove_header ()

void
e_msg_composer_remove_header (EMsgComposer *composer,
                              const gchar *name);

Removes all custom headers matching name that were added with e_msg_composer_add_header() or e_msg_composer_set_header().

Parameters

composer	an EMsgComposer
name	the header's name

e_msg_composer_set_draft_headers ()

void
e_msg_composer_set_draft_headers (EMsgComposer *composer,
                                  const gchar *folder_uri,
                                  const gchar *message_uid);

Add special X-Evolution-Draft headers to remember the most recently saved draft message, even across Evolution sessions. These headers can be used to mark the draft message for deletion after saving a newer draft or sending the composed message.

Parameters

composer	an EMsgComposer
folder_uri	folder URI of the last saved draft
message_uid	message UID of the last saved draft

e_msg_composer_set_source_headers ()

void
e_msg_composer_set_source_headers (EMsgComposer *composer,
                                   const gchar *folder_uri,
                                   const gchar *message_uid,
                                   CamelMessageFlags flags);

Add special X-Evolution-Source headers to remember the message being forwarded or replied to, even across Evolution sessions. These headers can be used to set appropriate flags on the source message after sending the composed message.

Parameters

composer	an EMsgComposer
folder_uri	folder URI of the source message
message_uid	message UID of the source message
flags	flags to set on the source message after sending

e_msg_composer_attach ()

void
e_msg_composer_attach (EMsgComposer *composer,
                       CamelMimePart *mime_part);

Attaches attachment to the message being composed in the composer.

Parameters

composer	a composer object
mime_part	the CamelMimePart to attach

e_msg_composer_set_alternative_body ()

void
e_msg_composer_set_alternative_body (EMsgComposer *composer,
                                     CamelMimePart *mime_part);

Sets the mime_part as an alternative body to the composer content. It should not be "text/plain" nor "text/html" and it should be the best format, because it's added as the last part of the "multipart/alternative" code.

It is still shown as a regular attachment in the GUI, thus the user can review or delete it.

Parameters

composer	an EMsgComposer
mime_part	the CamelMimePart to attach

Since: 3.50

e_msg_composer_get_message ()

void
e_msg_composer_get_message (EMsgComposer *composer,
                            gint io_priority,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Retrieve the message edited by the user as a CamelMimeMessage. The CamelMimeMessage object is created on the fly; subsequent calls to this function will always create new objects from scratch.

Parameters

composer

an EMsgComposer

e_msg_composer_get_message_finish ()

CamelMimeMessage *
e_msg_composer_get_message_finish (EMsgComposer *composer,
                                   GAsyncResult *result,
                                   GError **error);

e_msg_composer_get_message_print ()

void
e_msg_composer_get_message_print (EMsgComposer *composer,
                                  gint io_priority,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

e_msg_composer_get_message_print_finish ()

CamelMimeMessage *
e_msg_composer_get_message_print_finish
                               (EMsgComposer *composer,
                                GAsyncResult *result,
                                GError **error);

e_msg_composer_get_message_draft ()

void
e_msg_composer_get_message_draft (EMsgComposer *composer,
                                  gint io_priority,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

e_msg_composer_get_message_draft_finish ()

CamelMimeMessage *
e_msg_composer_get_message_draft_finish
                               (EMsgComposer *composer,
                                GAsyncResult *result,
                                GError **error);

e_msg_composer_get_from ()

CamelInternetAddress *
e_msg_composer_get_from (EMsgComposer *composer);

e_msg_composer_get_reply_to ()

CamelInternetAddress *
e_msg_composer_get_reply_to (EMsgComposer *composer);

e_msg_composer_add_message_attachments ()

void
e_msg_composer_add_message_attachments
                               (EMsgComposer *composer,
                                CamelMimeMessage *message,
                                gboolean just_inlines);

Walk through all the mime parts in message and add them to the composer specified in composer .

Parameters

composer	the composer to add the attachments to.
message	the source message to copy the attachments from.
just_inlines	whether to attach all attachments or just add inline images.

e_msg_composer_add_attachments_from_part_list ()

void
e_msg_composer_add_attachments_from_part_list
                               (EMsgComposer *composer,
                                EMailPartList *part_list,
                                gboolean just_inlines);

Walk through all the parts in part_list and add them to the composer .

Parameters

composer	the composer to add the attachments to
part_list	an EMailPartList with parts used to format the message
just_inlines	whether to attach all attachments or just add inline images

Since: 3.42

e_msg_composer_check_inline_attachments ()

void
e_msg_composer_check_inline_attachments
                               (EMsgComposer *composer);

Checks which inline attachments are referenced in the message body and those which are not referenced are added as regular attachments.

Parameters

composer

an EMsgComposer

Since: 3.44

e_msg_composer_request_close ()

void
e_msg_composer_request_close (EMsgComposer *composer);

e_msg_composer_can_close ()

gboolean
e_msg_composer_can_close (EMsgComposer *composer,
                          gboolean can_save_draft);

e_msg_composer_get_header_table ()

EComposerHeaderTable *
e_msg_composer_get_header_table (EMsgComposer *composer);

e_msg_composer_get_attachment_view ()

EAttachmentView *
e_msg_composer_get_attachment_view (EMsgComposer *composer);

e_msg_composer_get_raw_message_text_without_signature ()

GByteArray *
e_msg_composer_get_raw_message_text_without_signature
                               (EMsgComposer *composer);

Returns the text/plain of the message from composer without signature

e_msg_composer_get_raw_message_text ()

GByteArray *
e_msg_composer_get_raw_message_text (EMsgComposer *composer);

Returns the text/plain of the message from composer

e_msg_composer_is_exiting ()

gboolean
e_msg_composer_is_exiting (EMsgComposer *composer);

e_save_spell_languages ()

void
e_save_spell_languages (const GList *spell_languages);

e_msg_composer_save_focused_widget ()

void
e_msg_composer_save_focused_widget (EMsgComposer *composer);

e_msg_composer_restore_focus_on_composer ()

void
e_msg_composer_restore_focus_on_composer
                               (EMsgComposer *composer);

e_msg_composer_is_busy ()

gboolean
e_msg_composer_is_busy (EMsgComposer *composer);

Returns TRUE only while an EActivity is in progress.

Parameters

composer

an EMsgComposer

Returns

whether composer is busy

e_msg_composer_is_soft_busy ()

gboolean
e_msg_composer_is_soft_busy (EMsgComposer *composer);

Parameters

composer

an EMsgComposer

Returns

TRUE when e_msg_composer_is_busy() returns TRUE or when the asynchronous operations are disabled.

Since: 3.30

e_msg_composer_get_is_reply_or_forward ()

gboolean
e_msg_composer_get_is_reply_or_forward
                               (EMsgComposer *composer);

e_msg_composer_set_is_reply_or_forward ()

void
e_msg_composer_set_is_reply_or_forward
                               (EMsgComposer *composer,
                                gboolean is_reply_or_forward);

e_msg_composer_check_autocrypt ()

void
e_msg_composer_check_autocrypt (EMsgComposer *composer,
                                CamelMimeMessage *original_message);

e_msg_composer_set_is_imip ()

void
e_msg_composer_set_is_imip (EMsgComposer *composer,
                            gboolean is_imip);

e_msg_composer_get_is_imip ()

gboolean
e_msg_composer_get_is_imip (EMsgComposer *composer);

Property Details

The `“busy”` property

  “busy”                     gboolean

Whether an activity is in progress.

Owner: EMsgComposer

Flags: Read

Default value: FALSE

The `“editor”` property

  “editor”                   EHTMLEditor *

Owner: EMsgComposer

Flags: Read / Write / Construct Only

The `“focus-tracker”` property

  “focus-tracker”            EFocusTracker *

Owner: EMsgComposer

Flags: Read

The `“is-reply-or-forward”` property

  “is-reply-or-forward”      gboolean

Whether the composed message is a reply or a forward message.

Owner: EMsgComposer

Flags: Read / Write

Default value: FALSE

The `“shell”` property

  “shell”                    EShell *

The EShell singleton.

Owner: EMsgComposer

Flags: Read / Write / Construct Only

The `“soft-busy”` property

  “soft-busy”                gboolean

Whether asynchronous actions are disabled.

Owner: EMsgComposer

Flags: Read

Default value: FALSE

Signal Details

The `“before-destroy”` signal

void
user_function (EMsgComposer *emsgcomposer,
               gpointer      user_data)

Flags: Run Last

The `“presend”` signal

gboolean
user_function (EMsgComposer *emsgcomposer,
               gpointer      user_data)

Flags: Run Last

The `“print”` signal

void
user_function (EMsgComposer           *emsgcomposer,
               GtkPrintOperationAction arg1,
               CamelMimeMessage       *arg2,
               EActivity              *arg3,
               gpointer                user_data)

Flags: Run Last

The `“save-to-drafts”` signal

void
user_function (EMsgComposer     *emsgcomposer,
               CamelMimeMessage *arg1,
               EActivity        *arg2,
               gpointer          user_data)

Flags: Run Last

The `“save-to-outbox”` signal

void
user_function (EMsgComposer     *emsgcomposer,
               CamelMimeMessage *arg1,
               EActivity        *arg2,
               gpointer          user_data)

Flags: Run Last

The `“send”` signal

void
user_function (EMsgComposer     *emsgcomposer,
               CamelMimeMessage *arg1,
               EActivity        *arg2,
               gpointer          user_data)

Flags: Run Last