Miscellaneous Utilities

## Miscellaneous Utilities Miscellaneous Utilities |

## Synopsis

    #include <e-util/e-util.h>

    const gchar *       e_get_accels_filename               (void);
    void                e_show_uri                          (GtkWindow *parent,
                                                             const gchar *uri);
    void                e_display_help                      (GtkWindow *parent,
                                                             const gchar *link_id);
    GtkAction *         e_lookup_action                     (GtkUIManager *ui_manager,
                                                             const gchar *action_name);
    GtkActionGroup *    e_lookup_action_group               (GtkUIManager *ui_manager,
                                                             const gchar *group_name);
    gint                e_action_compare_by_label           (GtkAction *action1,
                                                             GtkAction *action2);
    void                e_action_group_remove_all_actions   (GtkActionGroup *action_group);
    GtkRadioAction *    e_radio_action_get_current_action   (GtkRadioAction *radio_action);
    void                e_categories_add_change_hook        (GHookFunc func,
                                                             gpointer object);
    gchar *             e_str_without_underscores           (const gchar *string);
    gint                e_str_compare                       (gconstpointer x,
                                                             gconstpointer y);
    gint                e_str_case_compare                  (gconstpointer x,
                                                             gconstpointer y);
    gint                e_collate_compare                   (gconstpointer x,
                                                             gconstpointer y);
    gint                e_int_compare                       (gconstpointer x,
                                                             gconstpointer y);
    guint32             e_color_to_value                    (GdkColor *color);
    gchar *             e_format_number                     (gint number);
    gint                (*ESortCompareFunc)                 (gconstpointer first,
                                                             gconstpointer second,
                                                             gpointer closure);
    void                e_bsearch                           (gconstpointer key,
                                                             gconstpointer base,
                                                             gsize nmemb,
                                                             gsize size,
                                                             ESortCompareFunc compare,
                                                             gpointer closure,
                                                             gsize *start,
                                                             gsize *end);
    gsize               e_strftime_fix_am_pm                (gchar *str,
                                                             gsize max,
                                                             const gchar *fmt,
                                                             const struct tm *tm);
    gsize               e_utf8_strftime_fix_am_pm           (gchar *str,
                                                             gsize max,
                                                             const gchar *fmt,
                                                             const struct tm *tm);
    const gchar *       e_get_month_name                    (GDateMonth month,
                                                             gboolean abbreviated);
    const gchar *       e_get_weekday_name                  (GDateWeekday weekday,
                                                             gboolean abbreviated);
    gdouble             e_flexible_strtod                   (const gchar *nptr,
                                                             gchar **endptr);
    gchar *             e_ascii_dtostr                      (gchar *buffer,
                                                             gint buf_len,
                                                             const gchar *format,
                                                             gdouble d);
    gboolean            e_file_lock_create                  (void);
    void                e_file_lock_destroy                 (void);
    gboolean            e_file_lock_exists                  (void);
    gchar *             e_util_guess_mime_type              (const gchar *filename,
                                                             gboolean localfile);
    GSList *            e_util_get_category_filter_options  (void);
    gboolean            e_binding_transform_color_to_string (GBinding *binding,
                                                             const GValue *source_value,
                                                             GValue *target_value,
                                                             gpointer not_used);
    gboolean            e_binding_transform_string_to_color (GBinding *binding,
                                                             const GValue *source_value,
                                                             GValue *target_value,
                                                             gpointer not_used);
    gboolean            e_binding_transform_source_to_uid   (GBinding *binding,
                                                             const GValue *source_value,
                                                             GValue *target_value,
                                                             ESourceList *source_list);
    gboolean            e_binding_transform_uid_to_source   (GBinding *binding,
                                                             const GValue *source_value,
                                                             GValue *target_value,
                                                             ESourceList *source_list);
    GSList *            e_charset_add_radio_actions         (GtkActionGroup *action_group,
                                                             const gchar *action_prefix,
                                                             const gchar *default_charset,
                                                             GCallback callback,
                                                             gpointer user_data);
    EActivity *         e_file_replace_contents_async       (GFile *file,
                                                             const gchar *contents,
                                                             gsize length,
                                                             const gchar *etag,
                                                             gboolean make_backup,
                                                             GFileCreateFlags flags,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_file_replace_contents_finish      (GFile *file,
                                                             GAsyncResult *result,
                                                             gchar **new_etag,
                                                             GError **error);
    gchar *             e_mktemp                            (const gchar *template);
    gint                e_mkstemp                           (const gchar *template);
    gchar *             e_mkdtemp                           (const gchar *template);

## Description

## Details

### 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`.

`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`.

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

### 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.

`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.

`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()`.

`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.

`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.

`radio_action` : | a GtkRadioAction
Returns : | the currently active group member

### 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.

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

### 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()`.

`string` : | the string to strip underscores from
Returns : | a newly-allocated string without underscores

### 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                    (GdkColor *color);

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

`color` : | a GdkColor
Returns : | a 24-bit color value

### 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_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.

`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.

`weekday` : | weekday index
`abbreviated` : | if `TRUE`, abbreviate the weekday name
Returns : | localized weekday name

### 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`.

`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.

`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_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_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()`.

`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 the MIME type could not be determined

### e_util_get_category_filter_options ()

    GSList *            e_util_get_category_filter_options  (void);

### 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.

`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.

`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,
                                                             ESourceList *source_list);

Transforms an ESource object to its UID string.

`binding` : | a GBinding
`source_value` : | a GValue of type E_TYPE_SOURCE
`target_value` : | a GValue of type G_TYPE_STRING
`source_list` : | an ESourceList
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,
                                                             ESourceList *source_list);

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

`binding` : | a GBinding
`source_value` : | a GValue of type G_TYPE_STRING
`target_value` : | a GValue of type E_TYPE_SOURCe
`source_list` : | an ESourceList
Returns : | `TRUE` if `source_list` had an ESource object with a matching UID string

### e_charset_add_radio_actions ()

    GSList *            e_charset_add_radio_actions         (GtkActionGroup *action_group,
                                                             const gchar *action_prefix,
                                                             const gchar *default_charset,
                                                             GCallback callback,
                                                             gpointer user_data);

Adds a set of GtkRadioActions for available character sets to `action_group`. The `default_charset` (or locale character set if `default_charset` is `NULL`) will be added first, and selected by default (except that ISO-8859-1 will always be used instead of US-ASCII). Any other character sets of the same language class as the default will be added next, followed by the remaining character sets.

`action_group` : | a GtkActionGroup
`action_prefix` : | a prefix for action names, or `NULL`
`default_charset` : | the default character set, or `NULL` to use the locale character set
`callback` : | a callback function for actions in the group, or `NULL`
`user_data` : | user data to be passed to `callback`, or `NULL`
Returns : | the radio action group

### e_file_replace_contents_async ()

    EActivity *         e_file_replace_contents_async       (GFile *file,
                                                             const gchar *contents,
                                                             gsize length,
                                                             const gchar *etag,
                                                             gboolean make_backup,
                                                             GFileCreateFlags flags,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

This is a wrapper for `g_file_replace_contents_async()` that also returns an EActivity to track the file operation. Cancelling the activity will cancel the file operation. See `g_file_replace_contents_async()` for more details.

`file` : | input GFile
`contents` : | string of contents to replace the file with
`length` : | the length of `contents` in bytes
`etag` : | a new entity tag for the `file`, or `NULL`
`make_backup` : | `TRUE` if a backup should be created
`flags` : | a set of GFileCreateFlags
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | the data to pass to the callback function
Returns : | an EActivity for the file operation

### e_file_replace_contents_finish ()

    gboolean            e_file_replace_contents_finish      (GFile *file,
                                                             GAsyncResult *result,
                                                             gchar **new_etag,
                                                             GError **error);

Finishes an asynchronous replace of the given `file`. See `e_file_replace_contents_async()`. Sets `new_etag` to the new entity tag for the document, if present. Free it with `g_free()` when it is no longer needed.

`file` : | input GFile
`result` : | a GAsyncResult
`new_etag` : | return location for a new entity tag
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### e_mktemp ()

    gchar *             e_mktemp                            (const gchar *template);

### e_mkstemp ()

    gint                e_mkstemp                           (const gchar *template);

### e_mkdtemp ()

    gchar *             e_mkdtemp                           (const gchar *template);