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