Miscellaneous Utilities

Miscellaneous Utilities

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 ()
gchar * e_str_without_underscores ()
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 ()
gchar * e_format_number ()
gint (*ESortCompareFunc) ()
void e_bsearch ()
gsize e_strftime_fix_am_pm ()
gsize e_utf8_strftime_fix_am_pm ()
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 ()
gdouble e_flexible_strtod ()
#define E_ASCII_DTOSTR_BUF_SIZE
gchar * e_ascii_dtostr ()
gboolean e_file_lock_create ()
void e_file_lock_destroy ()
gboolean e_file_lock_exists ()
gchar * e_util_guess_mime_type ()
GSList * e_util_get_category_filter_options ()
GList * e_util_dup_searchable_categories ()
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 ()
GSList * e_charset_add_radio_actions ()
EActivity * e_file_replace_contents_async ()
gboolean e_file_replace_contents_finish ()
gchar * e_mktemp ()
gint e_mkstemp ()
gchar * e_mkdtemp ()
void e_widget_undo_attach ()
gboolean e_widget_undo_is_attached ()
gboolean e_widget_undo_has_undo ()
gboolean e_widget_undo_has_redo ()
gchar * e_widget_undo_describe_undo ()
gchar * e_widget_undo_describe_redo ()
void e_widget_undo_do_undo ()
void e_widget_undo_do_redo ()
void e_widget_undo_reset ()

Types and Values

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

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_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_BUF_SIZE

#define E_ASCII_DTOSTR_BUF_SIZE (DBL_DIG + 12 + 10)

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

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

Parameters

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.

Parameters

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.

Parameters

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

e_widget_undo_attach ()

void
e_widget_undo_attach (GtkWidget *widget,
                      struct _EFocusTracker *focus_tracker);

The function does nothing, if the widget is not of a supported type for undo functionality, same as when the undo is already attached. It is ensured that the actions of the provided focus_tracker are updated on change of the widget .

See e_widget_undo_is_attached() .

Parameters

widget

a GtkWidget, where to attach undo functionality

 

focus_tracker

an EFocusTracker, can be NULL

 

Since 3.12


e_widget_undo_is_attached ()

gboolean
e_widget_undo_is_attached (GtkWidget *widget);

Checks whether the given widget has already attached an undo functionality - it is done with e_widget_undo_attach() .

Parameters

widget

a GtkWidget, where to test whether undo functionality is attached.

 

Returns

Whether the given widget has already attached undo functionality.

Since 3.12


e_widget_undo_has_undo ()

gboolean
e_widget_undo_has_undo (GtkWidget *widget);

Parameters

widget

a GtkWidget

 

Returns

Whether the given widget has any undo available.

See: e_widget_undo_describe_undo , e_widget_undo_do_undo

Since 3.12


e_widget_undo_has_redo ()

gboolean
e_widget_undo_has_redo (GtkWidget *widget);

Parameters

widget

a GtkWidget

 

Returns

Whether the given widget has any redo available.

See: e_widget_undo_describe_redo , e_widget_undo_do_redo

Since 3.12


e_widget_undo_describe_undo ()

gchar *
e_widget_undo_describe_undo (GtkWidget *widget);

Parameters

widget

a GtkWidget

 

Returns

Description of a top undo action available for the widget , NULL when there is no undo action. Returned pointer, if not NULL, should be freed with g_free().

See: e_widget_undo_has_undo , e_widget_undo_do_undo .

[transfer full]

Since 3.12


e_widget_undo_describe_redo ()

gchar *
e_widget_undo_describe_redo (GtkWidget *widget);

Parameters

widget

a GtkWidget

 

Returns

Description of a top redo action available for the widget , NULL when there is no redo action. Returned pointer, if not NULL, should be freed with g_free().

See: e_widget_undo_has_redo , e_widget_undo_do_redo .

[transfer full]

Since 3.12


e_widget_undo_do_undo ()

void
e_widget_undo_do_undo (GtkWidget *widget);

Applies the top undo action on the widget , which also remembers a redo action. It does nothing if the widget doesn't have attached undo functionality (e_widget_undo_attach() ), neither when there is no undo action available.

See: e_widget_undo_attach , e_widget_undo_has_undo , e_widget_undo_describe_undo

Parameters

widget

a GtkWidget

 

Since 3.12


e_widget_undo_do_redo ()

void
e_widget_undo_do_redo (GtkWidget *widget);

Applies the top redo action on the widget , which also remembers an undo action. It does nothing if the widget doesn't have attached undo functionality (e_widget_undo_attach() ), neither when there is no redo action available.

See: e_widget_undo_attach , e_widget_undo_has_redo , e_widget_undo_describe_redo

Parameters

widget

a GtkWidget

 

Since 3.12


e_widget_undo_reset ()

void
e_widget_undo_reset (GtkWidget *widget);

Resets undo and redo stack to empty on a widget with attached undo functionality. It does nothing, if the widget does not have the undo functionality attached (see e_widget_undo_attach() ).

Parameters

widget

a GtkWidget, on which might be attached undo functionality

 

Since 3.12

Types and Values

enum EAutomaticActionPolicy

Used for automatable actions based on the user's preference. The user is initially asked whether to perform the action automatically, and is given either-or choices like "Yes, Always" or "No, Never". The user's response is then remembered for future sessions.

Members

E_AUTOMATIC_ACTION_POLICY_ASK

Ask the user whether to perform the action.

 

E_AUTOMATIC_ACTION_POLICY_ALWAYS

Perform the action without interrupting the user.

 

E_AUTOMATIC_ACTION_POLICY_NEVER

Do not perform the action and do not interrupt the user.

 

enum EDateWeekday

Enumeration representing a day of the week; E_DATE_MONDAY , E_DATE_TUESDAY , etc. G_DATE_BAD_WEEKDAY is an invalid weekday.

This enum type is intentionally compatible with GDateWeekday. It exists only because GLib does not provide a GEnumClass for GDateWeekday. If that ever changes, this enum can go away.

Members

E_DATE_BAD_WEEKDAY

Invalid value

 

E_DATE_MONDAY

Monday

 

E_DATE_TUESDAY

Tuesday

 

E_DATE_WEDNESDAY

Wednesday

 

E_DATE_THURSDAY

Thursday

 

E_DATE_FRIDAY

Friday

 

E_DATE_SATURDAY

Saturday

 

E_DATE_SUNDAY

Sunday

 

enum ERestoreWindowFlags

Members

E_RESTORE_WINDOW_SIZE

   

E_RESTORE_WINDOW_POSITION