Utility functions

Utility functions — Utility functions

Functions

Types and Values

#define ICAL_TIME_TYPE
#define MINUTES_PER_DAY
#define MAX_MINUTES

Description

Functions

ALIGNED()

#define ALIGNED(x)      (round (x) + 0.5)

gcal_clear_datetime()

#define gcal_clear_datetime(dt) g_clear_pointer (dt, g_date_time_unref)

icaltime_get_type ()

GType
icaltime_get_type (void);

datetime_compare_date ()

gint
datetime_compare_date (GDateTime *dt1,
                       GDateTime *dt2);

Compares the dates of dt1 and dt2 . The times are ignored.

Parameters

dt1

a GDateTime.

[nullable]

dt2

a GDateTime.

[nullable]

Returns

negative, 0 or positive


datetime_to_icaltime ()

icaltimetype *
datetime_to_icaltime (GDateTime *dt);

Converts the GDateTime's dt to an icaltimetype.

Parameters

dt

a GDateTime

 

Returns

a icaltimetype.

[transfer full]


datetime_is_date ()

gboolean
datetime_is_date (GDateTime *dt);

Checks if dt represents a date. A pure date has the values of hour, minutes and seconds set to 0.

Parameters

dt

a GDateTime

 

Returns

TRUE if dt is a date, FALSE if it's a timed datetime.


icaltime_to_datetime ()

GDateTime *
icaltime_to_datetime (const icaltimetype *date);

Converts the icaltimetype's date to a GDateTime. The timezone is preserved.

Parameters

date

an icaltimetype

 

Returns

a GDateTime.

[transfer full]


gcal_dup_icaltime ()

icaltimetype *
gcal_dup_icaltime (const icaltimetype *date);

Creates an exact copy of date .

Parameters

date

an icaltimetype

 

Returns

an icaltimetype.

[transfer full]


gcal_get_weekday ()

gchar *
gcal_get_weekday (gint i);

Retrieves the weekday name.

Parameters

i

the weekday index

 

Returns

the weekday name.

[transfer full]


gcal_get_month_name ()

gchar *
gcal_get_month_name (gint i);

Retrieves the month name.

Parameters

i

the month index

 

Returns

the month name.

[transfer full]


gcal_get_surface_from_color ()

cairo_surface_t *
gcal_get_surface_from_color (GdkRGBA *color,
                             gint size);

Creates a squared surface filled with color . The surface is always size x size .

Parameters

color

a GdkRGBA

 

size

the size of the surface

 

Returns

a cairo_surface_t.

[transfer full]


get_circle_surface_from_color ()

cairo_surface_t *
get_circle_surface_from_color (GdkRGBA *color,
                               gint size);

Creates a circular surface filled with color . The surface is always size x size .

Parameters

color

a GdkRGBA

 

size

the size of the surface

 

Returns

a cairo_surface_t.

[transfer full]


get_color_name_from_source ()

void
get_color_name_from_source (ESource *source,
                            GdkRGBA *out_color);

Utility function to retrieve the color from source .

Parameters

source

an ESource

 

out_color

return value for the color

 

get_desc_from_component ()

gchar *
get_desc_from_component (ECalComponent *component,
                         const gchar *joint_char);

Utility method to handle the extraction of the description from an ECalComponent. This cycle through the list of ECalComponentText and concatenate each string into one.

Parameters

component

an ECalComponent

 

joint_char

the character to use when merging event comments

 

Returns

(nullable)(transfer full) a new allocated string with the description


get_uuid_from_component ()

gchar *
get_uuid_from_component (ESource *source,
                         ECalComponent *component);

Obtains the uuid from a component in the form "source_uid:event_uid:event_rid" or "source:uid:event_uid" if the component doesn't hold a recurrence event

Parameters

source

an {link ESource}

 

component

an {link ECalComponent}

 

Returns

(Transfer full) a new allocated string with the description


get_first_weekday ()

gint
get_first_weekday (void);

Copied from Clocks, which by itself is copied from GtkCalendar.

Returns

the first weekday, from 0 to 6


build_component_from_details ()

ECalComponent *
build_component_from_details (const gchar *summary,
                              GDateTime *initial_date,
                              GDateTime *final_date);

Create a component with the provided details

Returns

an {link ECalComponent} object.

[transfer full]


icaltime_compare_date ()

gint
icaltime_compare_date (const icaltimetype *date1,
                       const icaltimetype *date2);

Compare date parts of icaltimetype objects. Returns negative value, 0 or positive value accordingly if date1 is before, same day of after date2.

As a bonus it returns the amount of days passed between two days on the same year.

Parameters

date1

an icaltimetype

 

date2

an icaltimetype

 

Returns

negative, 0 or positive


icaltime_compare_with_current ()

gint
icaltime_compare_with_current (const icaltimetype *date1,
                               const icaltimetype *date2,
                               time_t *current_time_t);

Compares date1 and date2 against the current time. Dates closer to the current date are sorted before.

Parameters

date1

an icaltimetype

 

date2

an icaltimetype

 

current_time_t

the current time

 

Returns

negative if date1 comes after date2 , 0 if they're equal, positive otherwise


get_start_of_week ()

GDateTime *
get_start_of_week (icaltimetype *date);

Retrieves the start of the week that date falls in. This function already takes the first weekday into account.

Parameters

date

an icaltimetype

 

Returns

a GDateTime with the start of the week.

[transfer full]


get_end_of_week ()

GDateTime *
get_end_of_week (icaltimetype *date);

Retrieves the end of the week that date falls in. This function already takes the first weekday into account.

Parameters

date

an icaltimetype

 

Returns

a GDateTime with the end of the week.

[transfer full]


is_clock_format_24h ()

gboolean
is_clock_format_24h (void);

Retrieves whether the current clock format is 12h or 24h based.

Returns

TRUE if the clock format is 24h, FALSE otherwise.


e_strftime_fix_am_pm ()

gsize
e_strftime_fix_am_pm (gchar *str,
                      gsize max,
                      const gchar *fmt,
                      const struct tm *tm);

Function to do a last minute fixup of the AM/PM stuff if the locale and gettext haven't done it right. Most English speaking countries except the USA use the 24 hour clock (UK, Australia etc). However since they are English nobody bothers to write a language translation (gettext) file. So the locale turns off the AM/PM, but gettext does not turn on the 24 hour clock. Leaving a mess.

This routine checks if AM/PM are defined in the locale, if not it forces the use of the 24 hour clock.

The function itself is a front end on strftime and takes exactly the same arguments.

TODO: Actually remove the 'p' from the fixed up string so that there isn't a stray space.


e_utf8_strftime_fix_am_pm ()

gsize
e_utf8_strftime_fix_am_pm (gchar *str,
                           gsize max,
                           const gchar *fmt,
                           const struct tm *tm);

Stolen from Evolution codebase. Selects the correct time format.

Returns

the size of the string


fix_popover_menu_icons ()

void
fix_popover_menu_icons (GtkPopover *popover);

Hackish code that inspects the popover's children, retrieve the hidden GtkImage buried under lots of widgets, and make it visible again.

Hopefully, we'll find a better way to do this in the long run.

Parameters

window

a GtkPopover

 

get_source_parent_name_color ()

void
get_source_parent_name_color (GcalManager *manager,
                              ESource *source,
                              gchar **name,
                              gchar **color);

Retrieves the name and the color of the ESource that is parent of source .

Parameters

manager

a GcalManager

 

source

an ESource

 

name

return location for the name.

[nullable]

color

return location for the color.

[nullable]

format_utc_offset ()

gchar *
format_utc_offset (gint64 offset);

Formats the UTC offset to a string that GTimeZone can parse. E.g. "-0300" or "+0530".

Parameters

offset

an UTC offset

 

Returns

a string representing the offset.

[transfer full]


get_alarm_trigger_minutes ()

gint
get_alarm_trigger_minutes (GcalEvent *event,
                           ECalComponentAlarm *alarm);

Calculates the number of minutes before event 's start time that the alarm should be triggered.

Parameters

event

a GcalEvent

 

alarm

a ECalComponentAlarm

 

Returns

the number of minutes before the event start that alarm will be triggered.


should_change_date_for_scroll ()

gboolean
should_change_date_for_scroll (gdouble *scroll_value,
                               GdkEventScroll *scroll_event);

Utility function to check if the date should change based on the scroll. The date is changed when the user scrolls too much on touchpad, or performs a rotation of the scroll button in a mouse.

Parameters

scroll_value

the current scroll value

 

scroll_event

the GdkEventScroll that is being parsed

 

Returns

TRUE if the date should change, FALSE otherwise.


is_source_enabled ()

gboolean
is_source_enabled (ESource *source);

Retrieves whether the source is enabled or not. Disabled sources don't show their events.

Parameters

source

an ESource

 

Returns

TRUE if source is enabled, FALSE otherwise.

Types and Values

ICAL_TIME_TYPE

#define ICAL_TIME_TYPE (icaltime_get_type ())

MINUTES_PER_DAY

#define MINUTES_PER_DAY 1440

MAX_MINUTES

#define MAX_MINUTES     (7 * MINUTES_PER_DAY)