Utility functions: GNOME Calendar Reference Manual

## Utility functions Utility functions — Utility functions |

## Functions

#define | ALIGNED()
#define | gcal_clear_datetime()
GType | icaltime_get_type ()
gint | datetime_compare_date ()
icaltimetype * | datetime_to_icaltime ()
gboolean | datetime_is_date ()
GDateTime * | icaltime_to_datetime ()
icaltimetype * | gcal_dup_icaltime ()
gchar * | gcal_get_weekday ()
gchar * | gcal_get_month_name ()
cairo_surface_t * | gcal_get_surface_from_color ()
cairo_surface_t * | get_circle_surface_from_color ()
void | get_color_name_from_source ()
gchar * | get_desc_from_component ()
gchar * | get_uuid_from_component ()
gint | get_first_weekday ()
ECalComponent * | build_component_from_details ()
gint | icaltime_compare_date ()
gint | icaltime_compare_with_current ()
GDateTime * | get_start_of_week ()
GDateTime * | get_end_of_week ()
gboolean | is_clock_format_24h ()
gsize | e_strftime_fix_am_pm ()
gsize | e_utf8_strftime_fix_am_pm ()
void | fix_popover_menu_icons ()
gboolean | uri_get_fields ()
void | get_source_parent_name_color ()
gchar * | format_utc_offset ()
gint | get_alarm_trigger_minutes ()
gboolean | should_change_date_for_scroll ()
gboolean | is_source_enabled ()

## Types and Values

#define | ICAL_TIME_TYPE
#define | MINUTES_PER_DAY
#define | MAX_MINUTES
enum | GcalWindowViewType

## Object Hierarchy

        GEnum
        ╰── GcalWindowViewType

## 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 |

### uri_get_fields ()

    gboolean
    uri_get_fields (const gchar *uri,
                    gchar **schema,
                    gchar **host,
                    gchar **path,
                    gboolean *is_file);

Split the given URI into the fields.

#### Parameters

uri | the URI |
schema | return location for the schema of the URI. | [nullable]
host | return location for the host of the URI. | [nullable]
path | return location for the resource path. | [nullable]

#### Returns

TRUE if `uri` could be parsed, FALSE otherwise

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

### enum GcalWindowViewType

Enum with the available views.

#### Members

GCAL_WINDOW_VIEW_DAY | Day view (not implemented) |
GCAL_WINDOW_VIEW_WEEK | Week view |
GCAL_WINDOW_VIEW_MONTH | Month view |
GCAL_WINDOW_VIEW_YEAR | Year view |
GCAL_WINDOW_VIEW_LIST | List (not implemented) |
GCAL_WINDOW_VIEW_SEARCH | Search view (partially implemented) |