e-misc-utils: Evolution Utilities Reference Manual

## e-misc-utils e-misc-utils |

## Functions

void | (*EForeachFunc) ()
const gchar * | e_get_accels_filename ()
void | e_show_uri ()
void | e_display_help ()
void | e_restore_window ()
GtkAction * | e_lookup_action ()
GtkActionGroup * | e_lookup_action_group ()
gint | e_action_compare_by_label ()
void | e_action_group_remove_all_actions ()
GtkRadioAction * | e_radio_action_get_current_action ()
void | e_action_group_add_actions_localized ()
GtkWidget * | e_builder_get_widget ()
void | e_load_ui_builder_definition ()
guint | e_load_ui_manager_definition ()
void | e_categories_add_change_hook ()
gdouble | e_flexible_strtod ()
gchar * | e_ascii_dtostr ()
gchar * | e_str_without_underscores ()
GString * | e_str_replace_string ()
gint | e_str_compare ()
gint | e_str_case_compare ()
gint | e_collate_compare ()
gint | e_int_compare ()
guint32 | e_color_to_value ()
guint32 | e_rgba_to_value ()
void | e_rgba_to_color ()
void | e_utils_get_theme_color ()
void | e_utils_get_theme_color_color ()
void | e_utils_shade_color ()
GdkRGBA | e_utils_get_text_color_for_background ()
gchar * | e_format_number ()
gint | (*ESortCompareFunc) ()
void | e_bsearch ()
gsize | e_strftime_fix_am_pm ()
gsize | e_utf8_strftime_fix_am_pm ()
gsize | e_utf8_strftime_match_lc_messages ()
const gchar * | e_get_month_name ()
const gchar * | e_get_weekday_name ()
GDateWeekday | e_weekday_get_next ()
GDateWeekday | e_weekday_get_prev ()
GDateWeekday | e_weekday_add_days ()
GDateWeekday | e_weekday_subtract_days ()
guint | e_weekday_get_days_between ()
gint | e_weekday_to_tm_wday ()
GDateWeekday | e_weekday_from_tm_wday ()
gboolean | e_file_lock_create ()
void | e_file_lock_destroy ()
gboolean | e_file_lock_exists ()
GPid | e_file_lock_get_pid ()
gchar * | e_util_guess_mime_type ()
GSList * | e_util_get_category_filter_options ()
GList * | e_util_dup_searchable_categories ()
gboolean | e_util_get_open_source_job_info ()
void | e_util_propagate_open_source_job_error ()
EClient * | e_util_open_client_sync ()
gboolean | e_binding_transform_color_to_string ()
gboolean | e_binding_transform_string_to_color ()
gboolean | e_binding_transform_source_to_uid ()
gboolean | e_binding_transform_uid_to_source ()
gboolean | e_binding_transform_text_non_null ()
gboolean | e_binding_transform_text_to_uri ()
gboolean | e_binding_transform_uri_to_text ()
GBinding * | e_binding_bind_object_text_property ()
gulong | e_signal_connect_notify ()
gulong | e_signal_connect_notify_after ()
gulong | e_signal_connect_notify_swapped ()
gulong | e_signal_connect_notify_object ()
void | e_signal_disconnect_notify_handler ()
GSettings * | e_util_ref_settings ()
void | e_util_cleanup_settings ()
gboolean | e_util_prompt_user ()
void | e_util_run_simple_async_result_in_thread ()
gboolean | e_util_is_running_gnome ()
gboolean | e_util_is_running_flatpak ()
void | e_util_set_entry_issue_hint ()
guint | e_util_normalize_font_size ()
void | e_util_init_main_thread ()
gboolean | e_util_is_main_thread ()
gchar * | e_util_save_image_from_clipboard ()
gboolean | e_util_check_gtk_bindings_in_key_press_event_cb ()
void | e_util_save_file_chooser_folder ()
void | e_util_load_file_chooser_folder ()
gboolean | e_util_get_webkit_developer_mode_enabled ()
gchar * | e_util_next_uri_from_uri_list ()
void | e_util_resize_window_for_screen ()
gboolean | e_util_query_ldap_root_dse_sync ()
gchar * | e_util_get_uri_tooltip ()
gchar * | e_util_get_language_name ()
gboolean | e_util_get_language_info ()
void | e_misc_util_free_global_memory ()
gboolean | e_util_can_preview_filename ()
void | e_util_markup_append_escaped ()
void | e_util_markup_append_escaped_text ()
void | e_util_enum_supported_locales ()
const ESupportedLocales * | e_util_get_supported_locales ()
void | e_util_ensure_scrolled_window_height ()
void | e_util_make_safe_filename ()
gboolean | e_util_setup_toolbar_icon_size ()
gboolean | e_util_get_use_header_bar ()

## Types and Values

enum | EFocus
enum | ERestoreWindowFlags
#define | E_ASCII_DTOSTR_BUF_SIZE
#define | E_UTILS_LIGHTNESS_MULT
#define | E_UTILS_DARKNESS_MULT
#define | E_UTILS_DEFAULT_THEME_BG_COLOR
#define | E_UTILS_DEFAULT_THEME_BASE_COLOR
#define | E_UTILS_DEFAULT_THEME_FG_COLOR
#define | E_UTILS_DEFAULT_THEME_TEXT_COLOR
#define | E_UTILS_DEFAULT_THEME_SELECTED_BG_COLOR
#define | E_UTILS_DEFAULT_THEME_SELECTED_FG_COLOR
#define | E_UTILS_DEFAULT_THEME_UNFOCUSED_SELECTED_BG_COLOR
#define | E_UTILS_DEFAULT_THEME_UNFOCUSED_SELECTED_FG_COLOR
| ESupportedLocales

## Description

## Functions

### EForeachFunc ()

    void
    (*EForeachFunc) (gint model_row,
                     gpointer closure);

### e_get_accels_filename ()

    const gchar *
    e_get_accels_filename (void);

Returns the name of the user data file containing custom keyboard accelerator specifications.

#### Returns

filename for accelerator specifications

### e_show_uri ()

    void
    e_show_uri (GtkWindow *parent,
                const gchar *uri);

Launches the default application to show the given URI. The URI must be of a form understood by GIO. If the URI cannot be shown, it presents a dialog describing the error. The dialog is set as transient to `parent` if `parent` is non-`NULL`.

#### Parameters

parent | a parent GtkWindow or `NULL` |
uri | the URI to show |

### e_display_help ()

    void
    e_display_help (GtkWindow *parent,
                    const gchar *link_id);

Opens the user documentation to the section given by `link_id` , or to the table of contents if `link_id` is `NULL`. If the user documentation cannot be opened, it presents a dialog describing the error. The dialog is set as transient to `parent` if `parent` is non-`NULL`.

#### Parameters

parent | a parent GtkWindow or `NULL` |
link_id | help section to present or `NULL` |

### e_restore_window ()

    void
    e_restore_window (GtkWindow *window,
                      const gchar *settings_path,
                      ERestoreWindowFlags flags);

This function can restore one of or both a window's size and position using GSettings keys at `settings_path` which conform to the relocatable schema "org.gnome.evolution.window".

If E_RESTORE_WINDOW_SIZE is present in `flags` , restore `window` 's previously recorded size and maximize state.

If E_RESTORE_WINDOW_POSITION is present in `flags` , move `window` to the previously recorded screen coordinates.

The respective GSettings values will be updated when the window is resized and/or moved.

#### Parameters

window | a GtkWindow |
settings_path | a GSettings path |
flags | flags indicating which window features to restore |

### e_lookup_action ()

    GtkAction *
    e_lookup_action (GtkUIManager *ui_manager,
                     const gchar *action_name);

Returns the first GtkAction named `action_name` by traversing the list of action groups in `ui_manager` . If no such action exists, the function emits a critical warning before returning `NULL`, since this probably indicates a programming error and most code is not prepared to deal with lookup failures.

#### Parameters

ui_manager | a GtkUIManager |
action_name | the name of an action |

#### Returns

the first GtkAction named `action_name`

### e_lookup_action_group ()

    GtkActionGroup *
    e_lookup_action_group (GtkUIManager *ui_manager,
                           const gchar *group_name);

Returns the GtkActionGroup in `ui_manager` named `group_name` . If no such action group exists, the function emits a critical warnings before returning `NULL`, since this probably indicates a programming error and most code is not prepared to deal with lookup failures.

#### Parameters

ui_manager | a GtkUIManager |
group_name | the name of an action group |

#### Returns

the GtkActionGroup named `group_name`

### e_action_compare_by_label ()

    gint
    e_action_compare_by_label (GtkAction *action1,
                               GtkAction *action2);

Compares the labels for `action1` and `action2` using `g_utf8_collate()`.

#### Parameters

action1 | a GtkAction |
action2 | a GtkAction |

#### Returns

< 0 if `action1` compares before `action2` , 0 if they compare equal, > 0 if `action1` compares after `action2`

### e_action_group_remove_all_actions ()

    void
    e_action_group_remove_all_actions (GtkActionGroup *action_group);

Removes all actions from the action group.

#### Parameters

action_group | a GtkActionGroup |

### e_radio_action_get_current_action ()

    GtkRadioAction *
    e_radio_action_get_current_action (GtkRadioAction *radio_action);

Returns the currently active member of the group to which `radio_action` belongs.

#### Parameters

radio_action | a GtkRadioAction |

#### Returns

the currently active group member

### e_action_group_add_actions_localized ()

    void
    e_action_group_add_actions_localized (GtkActionGroup *action_group,
                                          const gchar *translation_domain,
                                          const GtkActionEntry *entries,
                                          guint n_entries,
                                          gpointer user_data);

Adds GtkAction-s defined by `entries` to `action_group` , with action's label and tooltip localized in the given translation domain, instead of the domain set on the `action_group` .

#### Parameters

action_group | a GtkActionGroup to add `entries` to |
translation_domain | a translation domain to use to translate label and tooltip strings in `entries` |
entries | an array of action descriptions. | [array length=n_entries]
n_entries | the number of entries |
user_data | data to pass to the action callbacks |

Since: 3.4

### e_builder_get_widget ()

    GtkWidget *
    e_builder_get_widget (GtkBuilder *builder,
                          const gchar *widget_name);

Gets the widget named `widget_name` . Note that this function does not increment the reference count of the returned widget. If `widget_name` could not be found in the `builder` 's object tree, a run-time warning is emitted since this usually indicates a programming error.

This is a convenience function to work around the awkwardness of GtkBuilder returning GObject pointers, when the vast majority of the time you want a GtkWidget pointer.

If you need something from `builder` other than a GtkWidget, or you want to test for the existence of some widget name without incurring a run-time warning, use `gtk_builder_get_object()`.

#### Parameters

builder | a GtkBuilder |
widget_name | name of a widget in `builder` |

#### Returns

the widget named `widget_name` , or `NULL`

### e_load_ui_builder_definition ()

    void
    e_load_ui_builder_definition (GtkBuilder *builder,
                                  const gchar *basename);

Loads a UI definition into `builder` from Evolution's UI directory. Failure here is fatal, since the application can't function without its UI definitions.

#### Parameters

builder | a GtkBuilder |
basename | basename of the UI definition file |

### e_load_ui_manager_definition ()

    guint
    e_load_ui_manager_definition (GtkUIManager *ui_manager,
                                  const gchar *basename);

Loads a UI definition into `ui_manager` from Evolution's UI directory. Failure here is fatal, since the application can't function without its UI definitions.

#### Parameters

ui_manager | a GtkUIManager |
basename | basename of the UI definition file |

#### Returns

The merge ID for the merged UI. The merge ID can be used to unmerge the UI with `gtk_ui_manager_remove_ui()`.

### e_categories_add_change_hook ()

    void
    e_categories_add_change_hook (GHookFunc func,
                                  gpointer object);

A saner alternative to `e_categories_register_change_listener()`.

Adds a hook function to be called when a category is added, removed or modified. If `object` is not `NULL`, the hook function is automatically removed when `object` is finalized.

#### Parameters

func | a hook function |
object | a GObject to be passed to `func` , or `NULL` |

### e_flexible_strtod ()

    gdouble
    e_flexible_strtod (const gchar *nptr,
                       gchar **endptr);

Converts a string to a gdouble value. This function detects strings either in the standard C locale or in the current locale.

This function is typically used when reading configuration files or other non-user input that should not be locale dependent, but may have been in the past. To handle input from the user you should normally use the locale-sensitive system strtod function.

To convert from a double to a string in a locale-insensitive way, use `g_ascii_dtostr` .

#### Parameters

nptr | the string to convert to a numeric value. |
endptr | if non-NULL, it returns the character after the last character used in the conversion. |

#### Returns

the gdouble value

### e_ascii_dtostr ()

    gchar *
    e_ascii_dtostr (gchar *buffer,
                    gint buf_len,
                    const gchar *format,
                    gdouble d);

Converts a double to a string, using the '.' as decimal_point. To format the number you pass in a printf-style formating string. Allowed conversion specifiers are eEfFgG.

If you want to generates enough precision that converting the string back using `g_strtod` gives the same machine-number (on machines with IEEE compatible 64bit doubles) use the format string "%.17g". If you do this it is guaranteed that the size of the resulting string will never be larger than `G_ASCII_DTOSTR_BUF_SIZE` bytes.

#### Parameters

buffer | A buffer to place the resulting string in |
buf_len | The length of the buffer. |
format | The printf-style format to use for the code to use for converting. |
d | The double to convert |

#### Returns

the pointer to the buffer with the converted string

### e_str_without_underscores ()

    gchar *
    e_str_without_underscores (const gchar *string);

Strips underscores from a string in the same way `gtk_label_new_with_mnemonics` does. The returned string should be freed using `g_free()`.

#### Parameters

string | the string to strip underscores from |

#### Returns

a newly-allocated string without underscores

### e_str_replace_string ()

    GString *
    e_str_replace_string (const gchar *text,
                          const gchar *find,
                          const gchar *replace);

Replaces every occurrence of the string `before` with the string `after` in the string `text` and returns a GString with result that should be freed with `g_string_free()`.

#### Parameters

text | the string to replace |
before | the string to be replaced |
after | the string to replaced with |

#### Returns

a newly-allocated GString

### e_str_compare ()

    gint
    e_str_compare (gconstpointer x,
                   gconstpointer y);

### e_str_case_compare ()

    gint
    e_str_case_compare (gconstpointer x,
                        gconstpointer y);

### e_collate_compare ()

    gint
    e_collate_compare (gconstpointer x,
                       gconstpointer y);

### e_int_compare ()

    gint
    e_int_compare (gconstpointer x,
                   gconstpointer y);

### e_color_to_value ()

    guint32
    e_color_to_value (const GdkColor *color);

Converts a GdkColor to a 24-bit RGB color value.

#### Parameters

color | a GdkColor |

#### Returns

a 24-bit color value

### e_rgba_to_value ()

    guint32
    e_rgba_to_value (const GdkRGBA *rgba);

Converts GdkRGBA to a 24-bit RGB color value

#### Parameters

rgba | a GdkRGBA |

#### Returns

a 24-bit color value

### e_rgba_to_color ()

    void
    e_rgba_to_color (const GdkRGBA *rgba,
                     GdkColor *color);

Converts `rgba` into `color` , but loses the alpha channel from `rgba` .

#### Parameters

rgba | a source GdkRGBA |
color | a destination GdkColor |

### e_utils_get_theme_color ()

    void
    e_utils_get_theme_color (GtkWidget *widget,
                             const gchar *color_names,
                             const gchar *fallback_color_ident,
                             GdkRGBA *rgba);

Reads named theme color from a GtkStyleContext of `widget` . The `color_names` are read one after another from left to right, the next are meant as fallbacks, in case the theme doesn't define the previous color. If none is found then the `fallback_color_ident` is set to `rgba` .

#### Parameters

widget | a GtkWidget instance |
color_names | comma-separated theme color names |
fallback_color_ident | fallback color identificator, in a format for `gdk_rgba_parse()` |
rgba | where to store the read color |

### e_utils_get_theme_color_color ()

    void
    e_utils_get_theme_color_color (GtkWidget *widget,
                                   const gchar *color_names,
                                   const gchar *fallback_color_ident,
                                   GdkColor *color);

The same as `e_utils_get_theme_color()`, only populates GdkColor, instead of GdkRGBA.

#### Parameters

widget | a GtkWidget instance |
color_names | comma-separated theme color names |
fallback_color_ident | fallback color identificator, in a format for `gdk_rgba_parse()` |
color | where to store the read color |

### e_utils_shade_color ()

    void
    e_utils_shade_color (const GdkRGBA *a,
                         GdkRGBA *b,
                         gdouble mult);

### e_utils_get_text_color_for_background ()

    GdkRGBA
    e_utils_get_text_color_for_background (const GdkRGBA *bg_rgba);

### e_format_number ()

    gchar *
    e_format_number (gint number);

### ESortCompareFunc ()

    gint
    (*ESortCompareFunc) (gconstpointer first,
                         gconstpointer second,
                         gpointer closure);

### e_bsearch ()

    void
    e_bsearch (gconstpointer key,
               gconstpointer base,
               gsize nmemb,
               gsize size,
               ESortCompareFunc compare,
               gpointer closure,
               gsize *start,
               gsize *end);

### e_strftime_fix_am_pm ()

    gsize
    e_strftime_fix_am_pm (gchar *str,
                          gsize max,
                          const gchar *fmt,
                          const struct tm *tm);

### e_utf8_strftime_fix_am_pm ()

    gsize
    e_utf8_strftime_fix_am_pm (gchar *str,
                               gsize max,
                               const gchar *fmt,
                               const struct tm *tm);

### e_utf8_strftime_match_lc_messages ()

    gsize
    e_utf8_strftime_match_lc_messages (gchar *string,
                                       gsize max,
                                       const gchar *fmt,
                                       const struct tm *tm);

The UTF-8 equivalent of `e_strftime()`, which also makes sure that the locale used for time and date formatting matches the locale used by the application so that, for example, the quoted message header produced by the mail composer in a reply uses only one locale (i.e. LC_MESSAGES, where available, overrides LC_TIME for consistency).

#### Parameters

string | The string to store the result in. |
max | The size of the `string` . |
fmt | The formatting to use on `tm` . |
tm | The time value to format. |

#### Returns

The number of characters placed in `string` .

Since: 3.22

### e_get_month_name ()

    const gchar *
    e_get_month_name (GDateMonth month,
                      gboolean abbreviated);

Returns the localized name for `month` . If `abbreviated` is `TRUE`, returns the locale's abbreviated month name.

#### Parameters

month | month index |
abbreviated | if `TRUE`, abbreviate the month name |

#### Returns

localized month name

### e_get_weekday_name ()

    const gchar *
    e_get_weekday_name (GDateWeekday weekday,
                        gboolean abbreviated);

Returns the localized name for `weekday` . If `abbreviated` is `TRUE`, returns the locale's abbreviated weekday name.

#### Parameters

weekday | weekday index |
abbreviated | if `TRUE`, abbreviate the weekday name |

#### Returns

localized weekday name

### e_weekday_get_next ()

    GDateWeekday
    e_weekday_get_next (GDateWeekday weekday);

Returns the GDateWeekday after `weekday` .

#### Parameters

weekday | a GDateWeekday |

#### Returns

the day after `weekday`

### e_weekday_get_prev ()

    GDateWeekday
    e_weekday_get_prev (GDateWeekday weekday);

Returns the GDateWeekday before `weekday` .

#### Parameters

weekday | a GDateWeekday |

#### Returns

the day before `weekday`

### e_weekday_add_days ()

    GDateWeekday
    e_weekday_add_days (GDateWeekday weekday,
                        guint n_days);

Increments `weekday` by `n_days` .

#### Parameters

weekday | a GDateWeekday |
n_days | number of days to add |

#### Returns

a GDateWeekday

### e_weekday_subtract_days ()

    GDateWeekday
    e_weekday_subtract_days (GDateWeekday weekday,
                             guint n_days);

Decrements `weekday` by `n_days` .

#### Parameters

weekday | a GDateWeekday |
n_days | number of days to subtract |

#### Returns

a GDateWeekday

### e_weekday_get_days_between ()

    guint
    e_weekday_get_days_between (GDateWeekday weekday1,
                                GDateWeekday weekday2);

Counts the number of days starting at `weekday1` and ending at `weekday2` .

#### Parameters

weekday1 | a GDateWeekday |
weekday2 | a GDateWeekday |

#### Returns

the number of days

### e_weekday_to_tm_wday ()

    gint
    e_weekday_to_tm_wday (GDateWeekday weekday);

Converts a GDateWeekday to the numbering used in struct tm.

#### Parameters

weekday | a GDateWeekday |

#### Returns

number of days since Sunday (0 - 6)

### e_weekday_from_tm_wday ()

    GDateWeekday
    e_weekday_from_tm_wday (gint tm_wday);

Converts a weekday in the numbering used in struct tm to a GDateWeekday.

#### Parameters

tm_wday | number of days since Sunday (0 - 6) |

#### Returns

a GDateWeekday

### e_file_lock_create ()

    gboolean
    e_file_lock_create (void);

### e_file_lock_destroy ()

    void
    e_file_lock_destroy (void);

### e_file_lock_exists ()

    gboolean
    e_file_lock_exists (void);

### e_file_lock_get_pid ()

    GPid
    e_file_lock_get_pid (void);

### e_util_guess_mime_type ()

    gchar *
    e_util_guess_mime_type (const gchar *filename,
                            gboolean localfile);

Tries to determine the MIME type for `filename` . Free the returned string with `g_free()`.

#### Parameters

filename | a local file name, or URI |
localfile | `TRUE` to check the file content, FALSE to check only the name |

#### Returns

the MIME type of `filename` , or `NULL` if the MIME type could not be determined

### e_util_get_category_filter_options ()

    GSList *
    e_util_get_category_filter_options (void);

### e_util_dup_searchable_categories ()

    GList *
    e_util_dup_searchable_categories (void);

Returns a list of the searchable categories, with each item being a UTF-8 category name. The list should be freed with `g_list_free()` when done with it, and the items should be freed with `g_free()`. Everything can be freed at once using `g_list_free_full()`.

#### Returns

a list of searchable category names; free with `g_list_free_full()`.

[transfer full][element-type utf8]

### e_util_get_open_source_job_info ()

    gboolean
    e_util_get_open_source_job_info (const gchar *extension_name,
                                     const gchar *source_display_name,
                                     gchar **description,
                                     gchar **alert_ident,
                                     gchar **alert_arg_0);

Populates `description` , `alert_ident` and `alert_arg_0` to be used to open an ESource with extension `extension_name` . The values can be used for functions like `e_alert_sink_submit_thread_job()`.

If TRUE is returned, then the caller is responsible to free all `description` , `alert_ident` and `alert_arg_0` with `g_free()`, when no longer needed.

#### Parameters

extension_name | an extension name of the source |
source_display_name | an ESource's display name |
description | a description to use. | [out][transfer-full]
alert_ident | an alert ident to use on failure. | [out][transfer-full]
alert_arg_0 | an alert argument 0 to use on failure. | [out][transfer-full]

#### Returns

TRUE, if the values for `description` , `alert_ident` and `alert_arg_0` were set for the given `extension_name` ; when FALSE is returned, then none of these out variables are changed.

Since: 3.16

### e_util_propagate_open_source_job_error ()

    void
    e_util_propagate_open_source_job_error
                                   (struct _EAlertSinkThreadJobData *job_data,
                                    const gchar *extension_name,
                                    GError *local_error,
                                    GError **error);

Propagates (and cosumes) the `local_error` into the `error` , eventually changes alert_ident for the `job_data` for well-known error codes, where is available better error description.

#### Parameters

job_data | an EAlertSinkThreadJobData instance |
extension_name | what extension name had beeing opened |
local_error | a GError as obtained in a thread job; can be NULL for success. | [allow none]
error | an output GError, to which propagate the `local_error` . | [allow none]

Since: 3.16

### e_util_open_client_sync ()

    EClient *
    e_util_open_client_sync (struct _EAlertSinkThreadJobData *job_data,
                             struct _EClientCache *client_cache,
                             const gchar *extension_name,
                             ESource *source,
                             guint32 wait_for_connected_seconds,
                             GCancellable *cancellable,
                             GError **error);

### e_binding_transform_color_to_string ()

    gboolean
    e_binding_transform_color_to_string (GBinding *binding,
                                         const GValue *source_value,
                                         GValue *target_value,
                                         gpointer not_used);

Transforms a GdkColor value to a color string specification.

#### Parameters

binding | a GBinding |
source_value | a GValue of type GDK_TYPE_COLOR |
target_value | a GValue of type G_TYPE_STRING |
not_used | not used |

#### Returns

`TRUE` always

### e_binding_transform_string_to_color ()

    gboolean
    e_binding_transform_string_to_color (GBinding *binding,
                                         const GValue *source_value,
                                         GValue *target_value,
                                         gpointer not_used);

Transforms a color string specification to a GdkColor.

#### Parameters

binding | a GBinding |
source_value | a GValue of type G_TYPE_STRING |
target_value | a GValue of type GDK_TYPE_COLOR |
not_used | not used |

#### Returns

`TRUE` if color string specification was valid

### e_binding_transform_source_to_uid ()

    gboolean
    e_binding_transform_source_to_uid (GBinding *binding,
                                       const GValue *source_value,
                                       GValue *target_value,
                                       ESourceRegistry *registry);

Transforms an ESource object to its UID string.

#### Parameters

binding | a GBinding |
source_value | a GValue of type E_TYPE_SOURCE |
target_value | a GValue of type G_TYPE_STRING |
registry | an ESourceRegistry |

#### Returns

`TRUE` if `source_value` was an ESource object

### e_binding_transform_uid_to_source ()

    gboolean
    e_binding_transform_uid_to_source (GBinding *binding,
                                       const GValue *source_value,
                                       GValue *target_value,
                                       ESourceRegistry *registry);

Transforms an ESource UID string to the corresponding ESource object in `registry` .

#### Parameters

binding | a GBinding |
source_value | a GValue of type G_TYPE_STRING |
target_value | a GValue of type E_TYPE_SOURCe |
registry | an ESourceRegistry |

#### Returns

`TRUE` if `registry` had an ESource object with a matching UID string

### e_binding_transform_text_non_null ()

    gboolean
    e_binding_transform_text_non_null (GBinding *binding,
                                       const GValue *source_value,
                                       GValue *target_value,
                                       gpointer user_data);

Transforms a text value to a text value which is never NULL; an empty string is used instead of NULL.

#### Parameters

binding | a GBinding |
source_value | a GValue of type G_TYPE_STRING |
target_value | a GValue of type G_TYPE_STRING |
user_data | custom user data, unused |

#### Returns

`TRUE` on success

### e_binding_transform_text_to_uri ()

    gboolean
    e_binding_transform_text_to_uri (GBinding *binding,
                                     const GValue *source_value,
                                     GValue *target_value,
                                     gpointer not_used);

Transforms a URI string into a GUri. It expects the source object to be an ESourceExtension descendant, then it adds also the user name from its ESourceAuthentication extension.

#### Parameters

binding | a GBinding |
source_value | a GValue of type G_TYPE_STRING |
target_value | a GValue of boxed GUri |
not_used | not used |

#### Returns

`TRUE`

### e_binding_transform_uri_to_text ()

    gboolean
    e_binding_transform_uri_to_text (GBinding *binding,
                                     const GValue *source_value,
                                     GValue *target_value,
                                     gpointer not_used);

Transforms a GUri into a string.

#### Parameters

binding | a GBinding |
source_value | a GValue of boxed GUri |
target_value | a GValue of type G_TYPE_STRING |
not_used | not used |

#### Returns

`TRUE`

### e_binding_bind_object_text_property ()

    GBinding *
    e_binding_bind_object_text_property (gpointer source,
                                         const gchar *source_property,
                                         gpointer target,
                                         const gchar *target_property,
                                         GBindingFlags flags);

Installs a new text property object binding, using `e_binding_bind_property_full()`, with transform functions to make sure that a NULL pointer is not passed in either way. Instead of NULL an empty string is used.

#### Parameters

source | the source GObject |
source_property | the text property on the source to bind |
target | the target GObject |
target_property | the text property on the target to bind |
flags | flags to pass to `e_binding_bind_property_full()` |

#### Returns

the GBinding instance representing the binding between the two GObject instances; there applies the same rules to it as for the result of `e_binding_bind_property_full()`.

### e_signal_connect_notify ()

    gulong
    e_signal_connect_notify (gpointer instance,
                             const gchar *notify_name,
                             GCallback c_handler,
                             gpointer user_data);

This installs a special handler in front of `c_handler` , which will call the `c_handler` only if the property value changed since the last time it was checked. Due to this, these handlers cannot be disconnected by by any of the g_signal_handlers_* functions, but only with the returned handler ID. A convenient `e_signal_disconnect_notify_handler()` was added to make it easier.

### e_signal_connect_notify_after ()

    gulong
    e_signal_connect_notify_after (gpointer instance,
                                   const gchar *notify_name,
                                   GCallback c_handler,
                                   gpointer user_data);

This installs a special handler in front of `c_handler` , which will call the `c_handler` only if the property value changed since the last time it was checked. Due to this, these handlers cannot be disconnected by by any of the g_signal_handlers_* functions, but only with the returned handler ID. A convenient `e_signal_disconnect_notify_handler()` was added to make it easier.

### e_signal_connect_notify_swapped ()

    gulong
    e_signal_connect_notify_swapped (gpointer instance,
                                     const gchar *notify_name,
                                     GCallback c_handler,
                                     gpointer user_data);

This installs a special handler in front of `c_handler` , which will call the `c_handler` only if the property value changed since the last time it was checked. Due to this, these handlers cannot be disconnected by by any of the g_signal_handlers_* functions, but only with the returned handler ID. A convenient `e_signal_disconnect_notify_handler()` was added to make it easier.

### e_signal_connect_notify_object ()

    gulong
    e_signal_connect_notify_object (gpointer instance,
                                    const gchar *notify_name,
                                    GCallback c_handler,
                                    gpointer gobject,
                                    GConnectFlags connect_flags);

This installs a special handler in front of `c_handler` , which will call the `c_handler` only if the property value changed since the last time it was checked. Due to this, these handlers cannot be disconnected by by any of the g_signal_handlers_* functions, but only with the returned handler ID. A convenient `e_signal_disconnect_notify_handler()` was added to make it easier.

### e_signal_disconnect_notify_handler ()

    void
    e_signal_disconnect_notify_handler (gpointer instance,
                                        gulong *handler_id);

Convenient handler disconnect function to be used with returned handler IDs from: `e_signal_connect_notify()` `e_signal_connect_notify_after()` `e_signal_connect_notify_swapped()` `e_signal_connect_notify_object()` but not necessarily only with these functions.

### e_util_ref_settings ()

    GSettings *
    e_util_ref_settings (const gchar *schema_id);

Either returns an existing referenced GSettings object for the given `schema_id` , or creates a new one and remembers it for later use, to avoid having too many GSettings objects created for the same `schema_id` .

#### Parameters

schema_id | the id of the schema to reference settings for |

#### Returns

A GSettings for the given `schema_id` . The returned GSettings object is referenced, thus free it with `g_object_unref()` when done with it.

Since: 3.16

### e_util_cleanup_settings ()

    void
    e_util_cleanup_settings (void);

Frees all the memory taken by `e_util_ref_settings()`.

Since: 3.16

### e_util_prompt_user ()

    gboolean
    e_util_prompt_user (GtkWindow *parent,
                        const gchar *settings_schema,
                        const gchar *promptkey,
                        const gchar *tag,
                        ...);

Convenience function to query the user with a Yes/No dialog and a "Do not show this dialog again" checkbox. If the user checks that checkbox, then `promptkey` is set to `FALSE`, otherwise it is set to `TRUE`.

Returns `TRUE` if the user clicks Yes or `FALSE` otherwise.

#### Parameters

parent | parent window |
settings_schema | name of the settings schema where `promptkey` belongs. |
promptkey | settings key to check if we should prompt the user or not. |
tag | e_alert tag. |

### e_util_run_simple_async_result_in_thread ()

    void
    e_util_run_simple_async_result_in_thread
                                   (GSimpleAsyncResult *simple,
                                    GSimpleAsyncThreadFunc func,
                                    GCancellable *cancellable);

Similar to `g_simple_async_result_run_in_thread()`, except it doesn't use GTask internally, thus doesn't block the GTask thread pool with possibly long job.

It doesn't behave exactly the same as the `g_simple_async_result_run_in_thread()`, the `cancellable` checking is not done before the finish.

#### Parameters

simple | a GSimpleAsyncResult |
func | a GSimpleAsyncThreadFunc to execute in the thread |
cancellable | an optional GCancellable, or `NULL` |

Since: 3.18

### e_util_is_running_gnome ()

    gboolean
    e_util_is_running_gnome (void);

#### Returns

Whether the current running desktop environment is GNOME.

Since: 3.18

### e_util_is_running_flatpak ()

    gboolean
    e_util_is_running_flatpak (void);

#### Returns

Whether running in Flatpak.

Since: 3.32

### e_util_set_entry_issue_hint ()

    void
    e_util_set_entry_issue_hint (GtkWidget *entry,
                                 const gchar *hint);

Sets a `hint` on the secondary `entry` icon about an entered value issue, or unsets it, when the `hint` is `NULL`.

#### Parameters

entry | a GtkEntry |
hint | a hint to set, or `NULL` to unset. | [allow none]

Since: 3.20

### e_util_normalize_font_size ()

    guint
    e_util_normalize_font_size (GtkWidget *widget,
                                gdouble font_size);

### e_util_init_main_thread ()

    void
    e_util_init_main_thread (GThread *thread);

### e_util_is_main_thread ()

    gboolean
    e_util_is_main_thread (GThread *thread);

### e_util_save_image_from_clipboard ()

    gchar *
    e_util_save_image_from_clipboard (GtkClipboard *clipboard);

Saves the image from `clipboard` to a temporary file and returns its URI.

#### Parameters

clipboard | a GtkClipboard |
hint | a hint to set, or `NULL` to unset. | [allow none]

Since: 3.22

### e_util_check_gtk_bindings_in_key_press_event_cb ()

    gboolean
    e_util_check_gtk_bindings_in_key_press_event_cb
                                   (GtkWidget *widget,
                                    GdkEvent *event);

A callback function for GtkWidget::key-press-event signal, which checks whether currently focused widget inside `widget` , if it's a GtkWindow, or a toplevel window containing the `widget` , will consume the `event` due to gtk+ bindings and if so, then it'll stop processing the event further. When it's connected on a GtkWindow, then it can prevent the event to be used for shortcuts of actions.

#### Parameters

widget | a GtkWidget, most often a GtkWindow |
event | a GdkEventKey |

#### Returns

`TRUE` to stop other handlers from being invoked for the event, `FALSE` to propagate the event further.

Since: 3.22

### e_util_save_file_chooser_folder ()

    void
    e_util_save_file_chooser_folder (GtkFileChooser *file_chooser);

Saves the current folder of the `file_chooser` , thus it could be used by `e_util_load_file_chooser_folder()` to open it in the last chosen folder.

#### Parameters

file_chooser | a GtkFileChooser |

Since: 3.24

### e_util_load_file_chooser_folder ()

    void
    e_util_load_file_chooser_folder (GtkFileChooser *file_chooser);

Sets the current folder to the `file_chooser` to the one previously saved by `e_util_save_file_chooser_folder()`. The function does nothing if none or invalid is saved.

#### Parameters

file_chooser | a GtkFileChooser |

Since: 3.24

### e_util_get_webkit_developer_mode_enabled ()

    gboolean
    e_util_get_webkit_developer_mode_enabled
                                   (void);

#### Returns

Whether WebKit developer mode is enabled. This is read only once, thus any changes in the GSettings property require restart of the Evolution.

Since: 3.24

### e_util_next_uri_from_uri_list ()

    gchar *
    e_util_next_uri_from_uri_list (guchar **uri_list,
                                   gint *len,
                                   gint *list_len);

#### Parameters

uri_list | array of URIs separated by new lines |
len | a length of the found URI. | [out]
list_len | a length of the array. | [out]

#### Returns

A newly allocated string with found URI.

Since: 3.26

### e_util_resize_window_for_screen ()

    void
    e_util_resize_window_for_screen (GtkWindow *window,
                                     gint window_width,
                                     gint window_height,
                                     const GSList *children);

Calculates the size of the `window` considering preferred sizes of `children` , and shrinks the `window` in case it won't be completely visible on the screen it is assigned to.

#### Parameters

window | a GtkWindow |
window_width | the `window` width without `children` , or -1 to compute |
window_height | the `window` height without `children` , or -1 to compute |
children | (nullable): a GSList with children to calculate with. | [element-type GtkWidget]

Since: 3.26

### e_util_query_ldap_root_dse_sync ()

    gboolean
    e_util_query_ldap_root_dse_sync (const gchar *host,
                                     guint16 port,
                                     ESourceLDAPSecurity security,
                                     gchar ***out_root_dse,
                                     GCancellable *cancellable,
                                     GError **error);

Queries an LDAP server identified by `host` and `port` for supported search bases and returns them as a NULL-terminated array of strings at `out_root_dse` . It sets `out_root_dse` to NULL on error. Free the returned `out_root_dse` with `g_strfreev()` when no longer needed.

The function fails and sets `error` to G_IO_ERROR_NOT_SUPPORTED when Evolution had been compiled without LDAP support.

#### Parameters

host | an LDAP server host name |
port | an LDAP server port |
security | an `ESourceLDAPSecurity` to use for the connection |
out_root_dse | NULL-terminated array of the server root DSE-s, or `NULL` on error. | [out][transfer full]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.28

### e_util_get_uri_tooltip ()

    gchar *
    e_util_get_uri_tooltip (const gchar *uri);

### e_util_get_language_name ()

    gchar *
    e_util_get_language_name (const gchar *language_tag);

#### Parameters

language_tag | Language tag to get its name for, like "en_US" |

#### Returns

Newly allocated string with localized language name.

[transfer full]

Since: 3.32

### e_util_get_language_info ()

    gboolean
    e_util_get_language_info (const gchar *language_tag,
                              gchar **out_language_name,
                              gchar **out_country_name);

Splits language tag into a localized language name and country name (the variant). The `out_language_name` is always filled when the function returns `TRUE`, but the `out_countr_name` can be `NULL`. That's for cases when the `language_tag` contains only the country part, like "en".

The function returns `FALSE` when it could not decode language name from the given `language_tag` . When either of the `out_language_name` and `out_country_name` is non-NULL and the function returns `TRUE`, then their respective values should be freed with `g_free()`, when no longer needed.

#### Parameters

language_tag | Language tag to get its name for, like "en_US" |
out_language_name | Return location for the language name, or `NULL`. | [out][nullable][transfer full]
out_country_name | Return location for the country name, or `NULL`. | [out][nullable][transfer full]

#### Returns

`TRUE`, when could get at least language name from the `language_tag` , `FALSE` otherwise.

Since: 3.32

### e_misc_util_free_global_memory ()

    void
    e_misc_util_free_global_memory (void);

Frees global memory allocated by evolution-util library. This is usually called at the end of the application.

Since: 3.32

### e_util_can_preview_filename ()

    gboolean
    e_util_can_preview_filename (const gchar *filename);

#### Parameters

filename | a file name to test. | [nullable]

#### Returns

Whether the `filename` can be used to create a preview in GtkFileChooser and such widgets. For example directories, pipes and sockets cannot by used.

Since: 3.32

### e_util_markup_append_escaped ()

    void
    e_util_markup_append_escaped (GString *buffer,
                                  const gchar *format,
                                  ...);

Appends escaped markup text into `buffer` . This function is similar to `g_markup_printf_escaped()`, except it appends the escaped text into a GString.

#### Parameters

buffer | a GString buffer to append escaped text to |
format | printf-like format of the string to append |
... | arguments for the format |

Since: 3.36

### e_util_markup_append_escaped_text ()

    void
    e_util_markup_append_escaped_text (GString *buffer,
                                       const gchar *text);

Markup-escapes `text` and appends it to `buffer` .

#### Parameters

buffer | a GString buffer to append escaped text to |
text | a text to escape and append to the buffer |

Since: 3.46

### e_util_enum_supported_locales ()

    void
    e_util_enum_supported_locales (void);

### e_util_get_supported_locales ()

    const ESupportedLocales *
    e_util_get_supported_locales (void);

### e_util_ensure_scrolled_window_height ()

    void
    e_util_ensure_scrolled_window_height (GtkScrolledWindow *scrolled_window);

### e_util_make_safe_filename ()

    void
    e_util_make_safe_filename (gchar *filename);

### e_util_setup_toolbar_icon_size ()

    gboolean
    e_util_setup_toolbar_icon_size (GtkToolbar *toolbar,
                                    GtkIconSize default_size);

### e_util_get_use_header_bar ()

    gboolean
    e_util_get_use_header_bar (void);

## Types and Values

### enum EFocus

#### Members

E_FOCUS_NONE |  |
E_FOCUS_CURRENT |  |
E_FOCUS_START |  |
E_FOCUS_END |  |

### enum ERestoreWindowFlags

#### Members

E_RESTORE_WINDOW_SIZE |  |
E_RESTORE_WINDOW_POSITION |  |

### E_ASCII_DTOSTR_BUF_SIZE

    #define E_ASCII_DTOSTR_BUF_SIZE (DBL_DIG + 12 + 10)

### E_UTILS_LIGHTNESS_MULT

    #define E_UTILS_LIGHTNESS_MULT 1.3

### E_UTILS_DARKNESS_MULT

    #define E_UTILS_DARKNESS_MULT 0.7

### E_UTILS_DEFAULT_THEME_BG_COLOR

    #define E_UTILS_DEFAULT_THEME_BG_COLOR				"#AAAAAA"

### E_UTILS_DEFAULT_THEME_BASE_COLOR

    #define E_UTILS_DEFAULT_THEME_BASE_COLOR			"#FFFFFF"

### E_UTILS_DEFAULT_THEME_FG_COLOR

    #define E_UTILS_DEFAULT_THEME_FG_COLOR				"#000000"

### E_UTILS_DEFAULT_THEME_TEXT_COLOR

    #define E_UTILS_DEFAULT_THEME_TEXT_COLOR			"#000000"

### E_UTILS_DEFAULT_THEME_SELECTED_BG_COLOR

    #define E_UTILS_DEFAULT_THEME_SELECTED_BG_COLOR			"#729fcf"

### E_UTILS_DEFAULT_THEME_SELECTED_FG_COLOR

    #define E_UTILS_DEFAULT_THEME_SELECTED_FG_COLOR			"#000000"

### E_UTILS_DEFAULT_THEME_UNFOCUSED_SELECTED_BG_COLOR

    #define E_UTILS_DEFAULT_THEME_UNFOCUSED_SELECTED_BG_COLOR "#808080"

### E_UTILS_DEFAULT_THEME_UNFOCUSED_SELECTED_FG_COLOR

    #define E_UTILS_DEFAULT_THEME_UNFOCUSED_SELECTED_FG_COLOR "#000000"

### ESupportedLocales

    typedef struct {
    	const gchar *code; /* like 'en' */
    	const gchar *locale; /* like 'en_US' */
    } ESupportedLocales;