Evolution Utilities Reference Manual | ||||
---|---|---|---|---|
Top | Description |
Synopsis
enum EAutomaticActionPolicy; enum EDateWeekday; void (*EForeachFunc) (gint model_row
,gpointer closure
); 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
); enum ERestoreWindowFlags; void e_restore_window (GtkWindow *window
,const gchar *settings_path
,ERestoreWindowFlags flags
); 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_action_group_add_actions_localized (GtkActionGroup *action_group
,const gchar *translation_domain
,const GtkActionEntry *entries
,guint n_entries
,gpointer user_data
); GtkWidget * e_builder_get_widget (GtkBuilder *builder
,const gchar *widget_name
); void e_load_ui_builder_definition (GtkBuilder *builder
,const gchar *basename
); 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
); guint32 e_rgba_to_value (GdkRGBA *rgba
); 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
); GDateWeekday e_weekday_get_next (GDateWeekday weekday
); GDateWeekday e_weekday_get_prev (GDateWeekday weekday
); GDateWeekday e_weekday_add_days (GDateWeekday weekday
,guint n_days
); GDateWeekday e_weekday_subtract_days (GDateWeekday weekday
,guint n_days
); guint e_weekday_get_days_between (GDateWeekday weekday1
,GDateWeekday weekday2
); gint e_weekday_to_tm_wday (GDateWeekday weekday
); GDateWeekday e_weekday_from_tm_wday (gint tm_wday
); gdouble e_flexible_strtod (const gchar *nptr
,gchar **endptr
); #define E_ASCII_DTOSTR_BUF_SIZE 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
); GList * e_util_get_searchable_categories (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
,ESourceRegistry *registry
); gboolean e_binding_transform_uid_to_source (GBinding *binding
,const GValue *source_value
,GValue *target_value
,ESourceRegistry *registry
); 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
);
Details
enum EAutomaticActionPolicy
typedef enum { E_AUTOMATIC_ACTION_POLICY_ASK, E_AUTOMATIC_ACTION_POLICY_ALWAYS, E_AUTOMATIC_ACTION_POLICY_NEVER } 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.
enum EDateWeekday
typedef enum { E_DATE_BAD_WEEKDAY = G_DATE_BAD_WEEKDAY, E_DATE_MONDAY = G_DATE_MONDAY, E_DATE_TUESDAY = G_DATE_TUESDAY, E_DATE_WEDNESDAY = G_DATE_WEDNESDAY, E_DATE_THURSDAY = G_DATE_THURSDAY, E_DATE_FRIDAY = G_DATE_FRIDAY, E_DATE_SATURDAY = G_DATE_SATURDAY, E_DATE_SUNDAY = G_DATE_SUNDAY } 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.
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
.
|
a parent GtkWindow or NULL
|
|
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
.
|
a parent GtkWindow or NULL
|
|
help section to present or NULL
|
enum ERestoreWindowFlags
typedef enum { E_RESTORE_WINDOW_SIZE = 1 << 0, E_RESTORE_WINDOW_POSITION = 1 << 1 } ERestoreWindowFlags;
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.
|
a GtkWindow |
|
a GSettings path |
|
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.
|
a GtkUIManager |
|
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.
|
a GtkUIManager |
|
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()
.
|
a GtkAction |
|
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.
|
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.
|
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
.
|
a GtkActionGroup to add entries to |
|
a translation domain to use
to translate label and tooltip strings in entries
|
|
an array of action descriptions. [array length=n_entries] |
|
the number of entries |
|
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()
.
|
a GtkBuilder |
|
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.
|
a GtkBuilder |
|
basename of the UI definition file |
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.
|
a hook function |
|
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()
.
|
the string to strip underscores from |
Returns : |
a newly-allocated string without underscores |
e_color_to_value ()
guint32 e_color_to_value (GdkColor *color
);
Converts a GdkColor to a 24-bit RGB color value.
|
a GdkColor |
Returns : |
a 24-bit color value |
e_rgba_to_value ()
guint32 e_rgba_to_value (GdkRGBA *rgba
);
Converts GdkRGBA to a 24-bit RGB color value
|
a GdkRGBA |
Returns : |
a 24-bit color value |
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 index |
|
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 index |
|
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
.
|
a GDateWeekday |
Returns : |
the day after weekday
|
e_weekday_get_prev ()
GDateWeekday e_weekday_get_prev (GDateWeekday weekday
);
Returns the GDateWeekday before 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
.
|
a GDateWeekday |
|
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
.
|
a GDateWeekday |
|
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
.
|
a GDateWeekday |
|
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.
|
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.
|
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
.
|
the string to convert to a numeric value. |
|
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.
|
A buffer to place the resulting string in |
|
The length of the buffer. |
|
The printf-style format to use for the code to use for converting. |
|
The double to convert |
Returns : |
the pointer to the buffer with the converted string |
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()
.
|
a local file name, or URI |
|
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_searchable_categories ()
GList * e_util_get_searchable_categories (void
);
Returns : |
list of searchable categories only. The list should
be freed with g_list_free() when done with it, but the items
are internal strings, names of categories, which should not
be touched in other than read-only way, in other words the same
restrictions as for e_categories_get_list() applies here too. |
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.
|
a GBinding |
|
a GValue of type GDK_TYPE_COLOR |
|
a GValue of type G_TYPE_STRING |
|
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.
|
a GBinding |
|
a GValue of type G_TYPE_STRING |
|
a GValue of type GDK_TYPE_COLOR |
|
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.
|
a GBinding |
|
a GValue of type E_TYPE_SOURCE |
|
a GValue of type G_TYPE_STRING |
|
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
.
|
a GBinding |
|
a GValue of type G_TYPE_STRING |
|
a GValue of type E_TYPE_SOURCe |
|
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.
|
a GtkActionGroup |
|
a prefix for action names, or NULL
|
|
the default character set, or NULL to use the
locale character set |
|
a callback function for actions in the group, or NULL
|
|
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.
|
input GFile |
|
string of contents to replace the file with |
|
the length of contents in bytes |
|
a new entity tag for the file , or NULL
|
|
TRUE if a backup should be created |
|
a set of GFileCreateFlags |
|
a GAsyncReadyCallback to call when the request is satisfied |
|
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.
|
input GFile |
|
a GAsyncResult |
|
return location for a new entity tag |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE on failure |