EHTMLEditorSelection: Evolution Utilities Reference Manual

## EHTMLEditorSelection EHTMLEditorSelection |

## Functions

gboolean | e_html_editor_selection_has_text ()
gchar * | e_html_editor_selection_get_caret_word ()
void | e_html_editor_selection_replace_caret_word ()
EHTMLEditorSelectionAlignment | e_html_editor_selection_get_alignment ()
void | e_html_editor_selection_set_alignment ()
const gchar * | e_html_editor_selection_get_background_color ()
void | e_html_editor_selection_set_background_color ()
void | e_html_editor_selection_get_font_color ()
void | e_html_editor_selection_set_font_color ()
const gchar * | e_html_editor_selection_get_font_name ()
void | e_html_editor_selection_set_font_name ()
guint | e_html_editor_selection_get_font_size ()
void | e_html_editor_selection_set_font_size ()
EHTMLEditorSelectionBlockFormat | e_html_editor_selection_get_block_format ()
void | e_html_editor_selection_set_block_format ()
gboolean | e_html_editor_selection_is_citation ()
gboolean | e_html_editor_selection_is_indented ()
void | e_html_editor_selection_indent ()
void | e_html_editor_selection_unindent ()
gboolean | e_html_editor_selection_is_bold ()
void | e_html_editor_selection_set_bold ()
gboolean | e_html_editor_selection_is_italic ()
void | e_html_editor_selection_set_italic ()
gboolean | e_html_editor_selection_is_monospaced ()
void | e_html_editor_selection_set_monospaced ()
gboolean | e_html_editor_selection_is_superscript ()
void | e_html_editor_selection_set_superscript ()
gboolean | e_html_editor_selection_is_subscript ()
void | e_html_editor_selection_set_subscript ()
gboolean | e_html_editor_selection_is_underline ()
void | e_html_editor_selection_set_underline ()
void | e_html_editor_selection_unlink ()
void | e_html_editor_selection_create_link ()
const gchar * | e_html_editor_selection_get_string ()
void | e_html_editor_selection_replace ()
void | e_html_editor_selection_insert_html ()
void | e_html_editor_selection_insert_image ()
void | e_html_editor_selection_insert_text ()
void | e_html_editor_selection_wrap_lines ()
void | e_html_editor_selection_save ()
void | e_html_editor_selection_restore ()
void | e_html_editor_selection_move ()
void | e_html_editor_selection_extend ()

## Types and Values

enum | EHTMLEditorSelectionAlignment
enum | EHTMLEditorSelectionFontSize
enum | EHTMLEditorSelectionBlockFormat
enum | EHTMLEditorSelectionGranularity

## Description

## Functions

### e_html_editor_selection_has_text ()

    gboolean
    e_html_editor_selection_has_text (EHTMLEditorSelection *selection);

Returns whether current selection contains any text.

#### Parameters

selection | an EHTMLEditorSelection |

#### Returns

`TRUE` when current selection contains text, `FALSE` otherwise.

### e_html_editor_selection_get_caret_word ()

    gchar *
    e_html_editor_selection_get_caret_word
                                   (EHTMLEditorSelection *selection);

Returns word under cursor.

#### Parameters

selection | an EHTMLEditorSelection |

#### Returns

A newly allocated string with current caret word or `NULL` when there is no text under cursor or when selection is active. [transfer-full].

### e_html_editor_selection_replace_caret_word ()

    void
    e_html_editor_selection_replace_caret_word
                                   (EHTMLEditorSelection *selection,
                                    const gchar *replacement);

Replaces current word under cursor with `replacement` .

#### Parameters

selection | an EHTMLEditorSelection |
replacement | a string to replace current caret word with |

### e_html_editor_selection_get_alignment ()

    EHTMLEditorSelectionAlignment
    e_html_editor_selection_get_alignment (EHTMLEditorSelection *selection);

Returns alignment of current paragraph

#### Parameters

selection | an EHTMLEditorSelection |

#### Returns

EHTMLEditorSelectionAlignment

### e_html_editor_selection_set_alignment ()

    void
    e_html_editor_selection_set_alignment (EHTMLEditorSelection *selection,
                                           EHTMLEditorSelectionAlignment alignment);

Sets alignment of current paragraph to give `alignment` .

#### Parameters

selection | an EHTMLEditorSelection |
alignment | an EHTMLEditorSelectionAlignment value to apply |

### e_html_editor_selection_get_background_color ()

    const gchar *
    e_html_editor_selection_get_background_color
                                   (EHTMLEditorSelection *selection);

Returns background color of currently selected text or letter at current cursor position.

#### Parameters

selection | an EHTMLEditorSelection |

#### Returns

A string with code of current background color.

### e_html_editor_selection_set_background_color ()

    void
    e_html_editor_selection_set_background_color
                                   (EHTMLEditorSelection *selection,
                                    const gchar *color);

Changes background color of current selection or letter at current cursor position to `color` .

#### Parameters

selection | an EHTMLEditorSelection |
color | code of new background color to set |

### e_html_editor_selection_get_font_color ()

    void
    e_html_editor_selection_get_font_color
                                   (EHTMLEditorSelection *selection,
                                    GdkRGBA *rgba);

Sets `rgba` to contain color of current text selection or letter at current cursor position.

#### Parameters

selection | an EHTMLEditorSelection |
rgba | a GdkRGBA object to be set to current font color |

### e_html_editor_selection_set_font_color ()

    void
    e_html_editor_selection_set_font_color
                                   (EHTMLEditorSelection *selection,
                                    const GdkRGBA *rgba);

Sets font color of current selection or letter at current cursor position to color defined in `rgba` .

#### Parameters

selection | an EHTMLEditorSelection |
rgba | a GdkRGBA |

### e_html_editor_selection_get_font_name ()

    const gchar *
    e_html_editor_selection_get_font_name (EHTMLEditorSelection *selection);

Returns name of font used in current selection or at letter at current cursor position.

#### Parameters

selection | an EHTMLEditorSelection |

#### Returns

A string with font name. [transfer-none]

### e_html_editor_selection_set_font_name ()

    void
    e_html_editor_selection_set_font_name (EHTMLEditorSelection *selection,
                                           const gchar *font_name);

Sets font name of current selection or of letter at current cursor position to `font_name` .

#### Parameters

selection | an EHTMLEditorSelection |
font_name | a font name to apply |

### e_html_editor_selection_get_font_size ()

    guint
    e_html_editor_selection_get_font_size (EHTMLEditorSelection *selection);

### e_html_editor_selection_set_font_size ()

    void
    e_html_editor_selection_set_font_size (EHTMLEditorSelection *selection,
                                           guint font_size);

Sets font size of current selection or of letter at current cursor position to `font_size` .

#### Parameters

selection | an EHTMLEditorSelection |
font_size | point size to apply |

### e_html_editor_selection_get_block_format ()

    EHTMLEditorSelectionBlockFormat
    e_html_editor_selection_get_block_format
                                   (EHTMLEditorSelection *selection);

Returns block format of current paragraph.

#### Parameters

selection | an EHTMLEditorSelection |

#### Returns

EHTMLEditorSelectionBlockFormat

### e_html_editor_selection_set_block_format ()

    void
    e_html_editor_selection_set_block_format
                                   (EHTMLEditorSelection *selection,
                                    EHTMLEditorSelectionBlockFormat format);

Changes block format of current paragraph to `format` .

#### Parameters

selection | an EHTMLEditorSelection |
format | an EHTMLEditorSelectionBlockFormat value |

### e_html_editor_selection_is_citation ()

    gboolean
    e_html_editor_selection_is_citation (EHTMLEditorSelection *selection);

Returns whether current paragraph is a citation.

#### Parameters

selection | an EHTMLEditorSelection |

#### Returns

`TRUE` when current paragraph is a citation, `FALSE` otherwise.

### e_html_editor_selection_is_indented ()

    gboolean
    e_html_editor_selection_is_indented (EHTMLEditorSelection *selection);

Returns whether current paragraph is indented. This does not include citations. To check, whether paragraph is a citation, use `e_html_editor_selection_is_citation()`.

#### Parameters

selection | an EHTMLEditorSelection |

#### Returns

`TRUE` when current paragraph is indented, `FALSE` otherwise.

### e_html_editor_selection_indent ()

    void
    e_html_editor_selection_indent (EHTMLEditorSelection *selection);

Indents current paragraph by one level.

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_unindent ()

    void
    e_html_editor_selection_unindent (EHTMLEditorSelection *selection);

Unindents current paragraph by one level.

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_is_bold ()

    gboolean
    e_html_editor_selection_is_bold (EHTMLEditorSelection *selection);

Returns whether current selection or letter at current cursor position is bold.

Returns `TRUE` when selection is bold, `FALSE` otherwise.

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_set_bold ()

    void
    e_html_editor_selection_set_bold (EHTMLEditorSelection *selection,
                                      gboolean bold);

Toggles bold formatting of current selection or letter at current cursor position, depending on whether `bold` is `TRUE` or `FALSE` .

#### Parameters

selection | an EHTMLEditorSelection |
bold | `TRUE` to enable bold, `FALSE` to disable |

### e_html_editor_selection_is_italic ()

    gboolean
    e_html_editor_selection_is_italic (EHTMLEditorSelection *selection);

Returns whether current selection or letter at current cursor position is italic.

Returns `TRUE` when selection is italic, `FALSE` otherwise.

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_set_italic ()

    void
    e_html_editor_selection_set_italic (EHTMLEditorSelection *selection,
                                        gboolean italic);

Toggles italic formatting of current selection or letter at current cursor position, depending on whether `italic` is `TRUE` or `FALSE` .

#### Parameters

selection | an EHTMLEditorSelection |
italic | `TRUE` to enable italic, `FALSE` to disable |

### e_html_editor_selection_is_monospaced ()

    gboolean
    e_html_editor_selection_is_monospaced (EHTMLEditorSelection *selection);

Returns whether current selection or letter at current cursor position is monospaced.

Returns `TRUE` when selection is monospaced, `FALSE` otherwise.

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_set_monospaced ()

    void
    e_html_editor_selection_set_monospaced
                                   (EHTMLEditorSelection *selection,
                                    gboolean monospaced);

Toggles monospaced formatting of current selection or letter at current cursor position, depending on whether `monospaced` is `TRUE` or `FALSE` .

#### Parameters

selection | an EHTMLEditorSelection |
monospaced | `TRUE` to enable monospaced, `FALSE` to disable |

### e_html_editor_selection_is_superscript ()

    gboolean
    e_html_editor_selection_is_superscript
                                   (EHTMLEditorSelection *selection);

Returns whether current selection or letter at current cursor position is in superscript.

Returns `TRUE` when selection is in superscript, `FALSE` otherwise.

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_set_superscript ()

    void
    e_html_editor_selection_set_superscript
                                   (EHTMLEditorSelection *selection,
                                    gboolean superscript);

Toggles superscript of current selection or letter at current cursor position, depending on whether `superscript` is `TRUE` or `FALSE` .

#### Parameters

selection | an EHTMLEditorSelection |
superscript | `TRUE` to enable superscript, `FALSE` to disable |

### e_html_editor_selection_is_subscript ()

    gboolean
    e_html_editor_selection_is_subscript (EHTMLEditorSelection *selection);

Returns whether current selection or letter at current cursor position is in subscript.

Returns `TRUE` when selection is in subscript, `FALSE` otherwise.

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_set_subscript ()

    void
    e_html_editor_selection_set_subscript (EHTMLEditorSelection *selection,
                                           gboolean subscript);

Toggles subscript of current selection or letter at current cursor position, depending on whether `subscript` is `TRUE` or `FALSE` .

#### Parameters

selection | an EHTMLEditorSelection |
subscript | `TRUE` to enable subscript, `FALSE` to disable |

### e_html_editor_selection_is_underline ()

    gboolean
    e_html_editor_selection_is_underline (EHTMLEditorSelection *selection);

Returns whether current selection or letter at current cursor position is underlined.

Returns `TRUE` when selection is underlined, `FALSE` otherwise.

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_set_underline ()

    void
    e_html_editor_selection_set_underline (EHTMLEditorSelection *selection,
                                           gboolean underline);

Toggles underline formatting of current selection or letter at current cursor position, depending on whether `underline` is `TRUE` or `FALSE` .

#### Parameters

selection | an EHTMLEditorSelection |
underline | `TRUE` to enable underline, `FALSE` to disable |

### e_html_editor_selection_unlink ()

    void
    e_html_editor_selection_unlink (EHTMLEditorSelection *selection);

Removes any links (<A> elements) from current selection or at current cursor position.

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_create_link ()

    void
    e_html_editor_selection_create_link (EHTMLEditorSelection *selection,
                                         const gchar *uri);

Converts current selection into a link pointing to `url` .

#### Parameters

selection | an EHTMLEditorSelection |
uri | destination of the new link |

### e_html_editor_selection_get_string ()

    const gchar *
    e_html_editor_selection_get_string (EHTMLEditorSelection *selection);

Returns currently selected string.

#### Parameters

selection | an EHTMLEditorSelection |

#### Returns

A pointer to content of current selection. The string is owned by EHTMLEditorSelection and should not be free'd.

### e_html_editor_selection_replace ()

    void
    e_html_editor_selection_replace (EHTMLEditorSelection *selection,
                                     const gchar *new_string);

Replaces currently selected text with `new_string` .

#### Parameters

selection | an EHTMLEditorSelection |
new_string | a string to replace current selection with |

### e_html_editor_selection_insert_html ()

    void
    e_html_editor_selection_insert_html (EHTMLEditorSelection *selection,
                                         const gchar *html_text);

Insert `html_text` into document at current cursor position. When a text range is selected, it will be replaced by `html_text` .

#### Parameters

selection | an EHTMLEditorSelection |
html_text | an HTML code to insert |

### e_html_editor_selection_insert_image ()

    void
    e_html_editor_selection_insert_image (EHTMLEditorSelection *selection,
                                          const gchar *image_uri);

Inserts image at current cursor position using `image_uri` as source. When a text range is selected, it will be replaced by the image.

#### Parameters

selection | an EHTMLEditorSelection |
image_uri | an URI of the source image |

### e_html_editor_selection_insert_text ()

    void
    e_html_editor_selection_insert_text (EHTMLEditorSelection *selection,
                                         const gchar *plain_text);

Inserts `plain_text` at current cursor position. When a text range is selected, it will be replaced by `plain_text` .

#### Parameters

selection | an EHTMLEditorSelection |
plain_text | text to insert |

### e_html_editor_selection_wrap_lines ()

    void
    e_html_editor_selection_wrap_lines (EHTMLEditorSelection *selection);

Wraps all lines in current selection to be 71 characters long.

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_save ()

    void
    e_html_editor_selection_save (EHTMLEditorSelection *selection);

Saves current cursor position or current selection range. The selection can be later restored by calling `e_html_editor_selection_restore()`.

Note that calling `e_html_editor_selection_save()` overwrites previously saved position.

Note that this method inserts special markings into the HTML code that are used to later restore the selection. It can happen that by deleting some segments of the document some of the markings are deleted too. In that case restoring the selection by `e_html_editor_selection_restore()` can fail. Also by moving text segments (Cut & Paste) can result in moving the markings elsewhere, thus `e_html_editor_selection_restore()` will restore the selection incorrectly.

It is recommended to use this method only when you are not planning to make bigger changes to content or structure of the document (formatting changes are usually OK).

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_restore ()

    void
    e_html_editor_selection_restore (EHTMLEditorSelection *selection);

Restores cursor position or selection range that was saved by `e_html_editor_selection_save()`.

Note that calling this function without calling `e_html_editor_selection_save()` before is a programming error and the behavior is undefined.

#### Parameters

selection | an EHTMLEditorSelection |

### e_html_editor_selection_move ()

    void
    e_html_editor_selection_move (EHTMLEditorSelection *selection,
                                  gboolean forward,
                                  EHTMLEditorSelectionGranularity granularity);

Moves current selection in given direction by given granularity

#### Parameters

selection | an EHTMLEditorSelection |
forward | whether to move the selection forward or backward |
granularity | granularity of the movement |

### e_html_editor_selection_extend ()

    void
    e_html_editor_selection_extend (EHTMLEditorSelection *selection,
                                    gboolean forward,
                                    EHTMLEditorSelectionGranularity granularity);

Extends current selection in given direction by given granularity.

#### Parameters

selection | an EHTMLEditorSelection |
forward | whether to extend selection forward or backward |
granularity | granularity of the extension |

## Types and Values

### enum EHTMLEditorSelectionAlignment

#### Members

E_HTML_EDITOR_SELECTION_ALIGNMENT_LEFT |  |
E_HTML_EDITOR_SELECTION_ALIGNMENT_CENTER |  |
E_HTML_EDITOR_SELECTION_ALIGNMENT_RIGHT |  |

### enum EHTMLEditorSelectionFontSize

#### Members

E_HTML_EDITOR_SELECTION_FONT_SIZE_TINY |  |
E_HTML_EDITOR_SELECTION_FONT_SIZE_SMALL |  |
E_HTML_EDITOR_SELECTION_FONT_SIZE_NORMAL |  |
E_HTML_EDITOR_SELECTION_FONT_SIZE_BIG |  |
E_HTML_EDITOR_SELECTION_FONT_SIZE_BIGGER |  |
E_HTML_EDITOR_SELECTION_FONT_SIZE_LARGE |  |
E_HTML_EDITOR_SELECTION_FONT_SIZE_VERY_LARGE |  |

### enum EHTMLEditorSelectionBlockFormat

#### Members

E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_NONE |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_PARAGRAPH |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_PRE |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_ADDRESS |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_BLOCKQUOTE |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_H1 |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_H2 |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_H3 |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_H4 |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_H5 |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_H6 |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_UNORDERED_LIST |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_ORDERED_LIST |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_ORDERED_LIST_ROMAN |  |
E_HTML_EDITOR_SELECTION_BLOCK_FORMAT_ORDERED_LIST_ALPHA |  |

### enum EHTMLEditorSelectionGranularity

#### Members

E_HTML_EDITOR_SELECTION_GRANULARITY_CHARACTER |  |
E_HTML_EDITOR_SELECTION_GRANULARITY_WORD |  |