EHTMLEditor: Evolution Utilities Reference Manual

## EHTMLEditor EHTMLEditor |

## Functions

void | e_html_editor_new ()
GtkWidget * | e_html_editor_new_finish ()
void | e_html_editor_connect_focus_tracker ()
GtkWidget * | e_html_editor_get_content_box ()
EContentEditor * | e_html_editor_get_content_editor ()
void | e_html_editor_register_content_editor ()
EContentEditorMode | e_html_editor_get_mode ()
void | e_html_editor_set_mode ()
void | e_html_editor_cancel_mode_change_content_update ()
EUIManager * | e_html_editor_get_ui_manager ()
EUIAction * | e_html_editor_get_action ()
gpointer | e_html_editor_get_ui_object ()
const gchar * | e_html_editor_get_filename ()
void | e_html_editor_set_filename ()
EActivityBar * | e_html_editor_get_activity_bar ()
EActivity * | e_html_editor_new_activity ()
void | e_html_editor_pack_above ()
void | e_html_editor_update_spell_actions ()
void | e_html_editor_save ()
gboolean | e_html_editor_save_finish ()
void | e_html_editor_add_cid_part ()
void | e_html_editor_remove_cid_part ()
void | e_html_editor_remove_unused_cid_parts ()
void | e_html_editor_remove_all_cid_parts ()
CamelMimePart * | e_html_editor_ref_cid_part ()
void | e_html_editor_clear_alerts ()
EAlertBar * | e_html_editor_get_alert_bar ()
GtkWidget * | e_html_editor_util_new_mode_combobox ()

## Properties

char * | filename | Read / Write
EContentEditorMode | mode | Read / Write
gboolean | paste-plain-prefer-pre | Read / Write

## Signals

void | after-mode-changed | Action
void | spell-languages-changed | Run Last
void | update-actions | Run Last

## Types and Values

#define | E_HTML_EDITOR_MAX_INDENT_LEVEL
#define | E_HTML_EDITOR_UI_OBJECT_MAIN_MENU
#define | E_HTML_EDITOR_UI_OBJECT_MAIN_TOOLBAR

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkGrid
                        ╰── EHTMLEditor

## Description

## Functions

### e_html_editor_new ()

    void
    e_html_editor_new (GAsyncReadyCallback callback,
                       gpointer user_data);

Constructs a new EHTMLEditor asynchronously. The result is returned by `e_html_editor_new_finish()`, which should be called inside `callback` .

#### Parameters

callback | a callback to be called when the editor is ready |
user_data | a used data passed into the `callback` |

Since: 3.22

### e_html_editor_new_finish ()

    GtkWidget *
    e_html_editor_new_finish (GAsyncResult *result,
                              GError **error);

Finishes the call of `e_html_editor_new()`.

#### Parameters

result | a GAsyncResult passed to callback from `e_html_editor_new()` |
error | an optional GError |

#### Returns

A newly created EHTMLEditor.

[transfer-full]

Since: 3.22

### e_html_editor_connect_focus_tracker ()

    void
    e_html_editor_connect_focus_tracker (EHTMLEditor *editor,
                                         EFocusTracker *focus_tracker);

Connects `editor` actions and widgets to the `focus_tracker` .

#### Parameters

editor | an EHTMLEditor |
focus_tracker | an EFocusTracker |

Since: 3.44

### e_html_editor_get_content_box ()

    GtkWidget *
    e_html_editor_get_content_box (EHTMLEditor *editor);

#### Parameters

editor | an EHTMLEditor |

#### Returns

the content box, the content editors are packed into.

[transfer none]

Since: 3.44

### e_html_editor_get_content_editor ()

    EContentEditor *
    e_html_editor_get_content_editor (EHTMLEditor *editor);

Returns instance of EContentEditor used in the `editor` .

#### Parameters

editor | an EHTMLEditor |

### e_html_editor_register_content_editor ()

    void
    e_html_editor_register_content_editor (EHTMLEditor *editor,
                                           const gchar *name,
                                           EContentEditor *cnt_editor);

### e_html_editor_get_mode ()

    EContentEditorMode
    e_html_editor_get_mode (EHTMLEditor *editor);

#### Parameters

editor | an EHTMLEditor |

#### Returns

Current editor mode, as an EContentEditorMode

Since: 3.44

### e_html_editor_set_mode ()

    void
    e_html_editor_set_mode (EHTMLEditor *editor,
                            EContentEditorMode mode);

Sets the editor mode.

#### Parameters

editor | an EHTMLEditor |
mode | an EContentEditorMode |

Since: 3.44

### e_html_editor_cancel_mode_change_content_update ()

    void
    e_html_editor_cancel_mode_change_content_update
                                   (EHTMLEditor *editor);

Cancels any ongoing content update after the mode change. This is useful when setting content before the read of the current editor's content is finished, which can happen due to reading the editor's content asynchronously.

#### Parameters

editor | an EHTMLEditor |

Since: 3.50

### e_html_editor_get_ui_manager ()

    EUIManager *
    e_html_editor_get_ui_manager (EHTMLEditor *editor);

Returns an EUIManager that manages all the actions in the `editor` .

#### Parameters

editor | an EHTMLEditor |

#### Returns

an internal EUIManager.

[transfer none]

### e_html_editor_get_action ()

    EUIAction *
    e_html_editor_get_action (EHTMLEditor *editor,
                              const gchar *action_name);

Gets action named `action_name` from the internal EUIManager.

#### Parameters

editor | an EHTMLEditor |
action_name | name of action to lookup and return |

#### Returns

an EUIAction matching `action_name` or `NULL`, if no such action exists.

[transfer none][nullable]

### e_html_editor_get_ui_object ()

    gpointer
    e_html_editor_get_ui_object (EHTMLEditor *editor,
                                 const gchar *object_name);

Gets a UI object (usually a GtkWidget descendant) by its name. There are only few objects recognized, namely: E_HTML_EDITOR_UI_OBJECT_MAIN_MENU: the main menu as an EUIMenu; E_HTML_EDITOR_UI_OBJECT_MAIN_TOOLBAR: the main toolbar as a GtkToolbar.

#### Parameters

editor | an EHTMLEditor |
object_name | an object name to get |

#### Returns

the UI object named `object_name` , or `NULL`, when the name is not recognized.

[transfer none][nullable]

Since: 3.56

### e_html_editor_get_filename ()

    const gchar *
    e_html_editor_get_filename (EHTMLEditor *editor);

Returns path and name of file to which content of the editor should be saved.

#### Parameters

editor | an EHTMLEditor |

### e_html_editor_set_filename ()

    void
    e_html_editor_set_filename (EHTMLEditor *editor,
                                const gchar *filename);

Sets file to which content of the editor should be saved (see `e_html_editor_save()`).

#### Parameters

editor | an EHTMLEditor |
filename | Target file |

### e_html_editor_get_activity_bar ()

    EActivityBar *
    e_html_editor_get_activity_bar (EHTMLEditor *editor);

### e_html_editor_new_activity ()

    EActivity *
    e_html_editor_new_activity (EHTMLEditor *editor);

Creates and configures a new EActivity so its progress is shown in the `editor` . The EActivity comes pre-loaded with a CamelOperation.

#### Parameters

editor | an EHTMLEditor |

#### Returns

a new EActivity for use with `editor`

### e_html_editor_pack_above ()

    void
    e_html_editor_pack_above (EHTMLEditor *editor,
                              GtkWidget *child);

Inserts `child` right between the toolbars and the editor widget itself.

#### Parameters

editor | an EHTMLEditor |
child | a GtkWidget |

### e_html_editor_update_spell_actions ()

    void
    e_html_editor_update_spell_actions (EHTMLEditor *editor);

### e_html_editor_save ()

    void
    e_html_editor_save (EHTMLEditor *editor,
                        const gchar *filename,
                        gboolean as_html,
                        GCancellable *cancellable,
                        GAsyncReadyCallback callback,
                        gpointer user_data);

Starts an asynchronous save of the current content of the EContentEditor into given file. When `as_html` is `FALSE` , the content is first converted into plain text.

Finish the call with `e_html_editor_save_finish()` from the `callback` .

#### Parameters

editor | an EHTMLEditor |
filename | file into which to save the content |
as_html | whether the content should be saved as HTML or plain text |
cancellable | an optional GCancellable, or `NULL` |
callback | a GAsyncReadyCallback to call when the save is finished. | [scope async]
user_data | user data passed to `callback` . | [closure callback]

Since: 3.38

### e_html_editor_save_finish ()

    gboolean
    e_html_editor_save_finish (EHTMLEditor *editor,
                               GAsyncResult *result,
                               GError **error);

Finished the previous call of `e_html_editor_save()`.

#### Parameters

editor | an EHTMLEditor |
result | a GAsyncResult of the operation |
error | return location for a GError, or `NULL` |

#### Returns

whether the save succeeded.

Since: 3.38

### e_html_editor_add_cid_part ()

    void
    e_html_editor_add_cid_part (EHTMLEditor *editor,
                                CamelMimePart *mime_part);

Add the `mime_part` with its Content-ID (if not set, one is assigned), which can be later obtained with `e_html_editor_ref_cid_part()`;

#### Parameters

editor | an EHTMLEditor |
mime_part | a CamelMimePart |

Since: 3.38

### e_html_editor_remove_cid_part ()

    void
    e_html_editor_remove_cid_part (EHTMLEditor *editor,
                                   const gchar *cid_uri);

Removes CID part with given `cid_uri` , previously added with `e_html_editor_add_cid_part()`. The function does nothing if no such part is stored.

#### Parameters

editor | an EHTMLEditor |
cid_uri | a Content ID URI (starts with "cid:") to remove |

Since: 3.38

### e_html_editor_remove_unused_cid_parts ()

    void
    e_html_editor_remove_unused_cid_parts (EHTMLEditor *editor,
                                           GSList *used_mime_parts,
                                           GSList **out_removed_mime_parts);

Traverses the list of "cid:" parts and removes all which are not part of the `used_mime_parts` .

The optional `out_removed_mime_parts` is filled with the removed parts. Free it with g_slist_free_full (list, g_object_unref);, when no longer needed.

#### Parameters

editor | an EHTMLEditor |
used_mime_parts | list of used CamelMimePart-s to keep. | [nullable][element-type CamelMimePart]
out_removed_mime_parts | list of removed parts. | [out][optional][element-type CamelMimePart][transfer full]

Since: 3.44

### e_html_editor_remove_all_cid_parts ()

    void
    e_html_editor_remove_all_cid_parts (EHTMLEditor *editor);

Removes all CID parts previously added with `e_html_editor_add_cid_part()`.

#### Parameters

editor | an EHTMLEditor |

Since: 3.38

### e_html_editor_ref_cid_part ()

    CamelMimePart *
    e_html_editor_ref_cid_part (EHTMLEditor *editor,
                                const gchar *cid_uri);

References a CamelMimePart with given `cid_uri` as Content ID, if previously added with `e_html_editor_add_cid_part()`. The `cid_uri` should start with "cid:".

The returned non-`NULL` object is references, thus it should be freed with `g_object_unref()`, when no longer needed.

#### Parameters

editor | an EHTMLEditor |
cid_uri | a Content ID URI (starts with "cid:") to obtain the part for |

#### Returns

a CamelMimePart with given Content ID, or `NULL`, if not found.

[transfer full][nullable]

Since: 3.38

### e_html_editor_clear_alerts ()

    void
    e_html_editor_clear_alerts (EHTMLEditor *editor);

Clears all shown alerts in the `editor` .

#### Parameters

editor | an EHTMLEditor |

Since: 3.50

### e_html_editor_get_alert_bar ()

    EAlertBar *
    e_html_editor_get_alert_bar (EHTMLEditor *editor);

Returns an EAlertBar used by the `editor` .

#### Parameters

editor | an EHTMLEditor |

#### Returns

an EAlertBar used by the `editor` .

[transfer none][nullable]

Since: 3.50

### e_html_editor_util_new_mode_combobox ()

    GtkWidget *
    e_html_editor_util_new_mode_combobox (const gchar *unknown_label);

Creates a new combo box containing all composer modes.

When `unknown_label` is not `NULL`, an extra entry for `E_CONTENT_EDITOR_MODE_UNKNOWN` is added with the given label, typically used for "Use global setting" in override combos.

It's a descendant of EActionComboBox, thus use `e_action_combo_box_get_current_value()` and `e_action_combo_box_set_current_value()` to get the currently selected mode.

#### Parameters

unknown_label | label for the "unknown" mode entry, or `NULL`. | [nullable]

#### Returns

a new GtkWidget, which is an EActionComboBox with composer modes.

[transfer full]

Since: 3.44

## Types and Values

### E_HTML_EDITOR_MAX_INDENT_LEVEL

    #define E_HTML_EDITOR_MAX_INDENT_LEVEL 10

### E_HTML_EDITOR_UI_OBJECT_MAIN_MENU

    #define E_HTML_EDITOR_UI_OBJECT_MAIN_MENU "main-menu"

### E_HTML_EDITOR_UI_OBJECT_MAIN_TOOLBAR

    #define E_HTML_EDITOR_UI_OBJECT_MAIN_TOOLBAR "main-toolbar"

## Property Details

### The `“filename”` property

      “filename”                 char *

Owner: EHTMLEditor

Flags: Read / Write

Default value: NULL

### The `“mode”` property

      “mode”                     EContentEditorMode

Owner: EHTMLEditor

Flags: Read / Write

Default value: E_CONTENT_EDITOR_MODE_HTML

### The `“paste-plain-prefer-pre”` property

      “paste-plain-prefer-pre”   gboolean

Owner: EHTMLEditor

Flags: Read / Write

Default value: FALSE

## Signal Details

### The `“after-mode-changed”` signal

    void
    user_function (EHTMLEditor *ehtmleditor,
                   gpointer     user_data)

Flags: Action

### The `“spell-languages-changed”` signal

    void
    user_function (EHTMLEditor *ehtmleditor,
                   gpointer     user_data)

Flags: Run Last

### The `“update-actions”` signal

    void
    user_function (EHTMLEditor *ehtmleditor,
                   guint        arg1,
                   char        *arg2,
                   char        *arg3,
                   gpointer     user_data)

Flags: Run Last