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);