GcalEvent

GcalEvent — A class that represents an event

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

gboolean all-day Read / Write
GdkRGBA * color Read / Write
ECalComponent * component Read / Write / Construct Only
GDateTime * date-end Read / Write
GDateTime * date-start Read / Write
gchar * description Read / Write
gboolean has-recurrence Read
gchar * location Read / Write
GcalRecurrence * recurrence Read / Write
ESource * source Read / Write / Construct
gchar * summary Read / Write
GTimeZone * timezone Read / Write
gchar * uid Read

Types and Values

Object Hierarchy

    GObject
    ╰── GcalEvent

Implemented Interfaces

GcalEvent implements GInitable.

Description

The GcalEvent class represents an appointment, with various functions to modify it. All the changes are transient. To persistently store the changes, you need to call gcal_manager_update_event().

Although the ECalComponent may have no end date. In this case, gcal_event_get_date_end() returns the same date that gcal_event_get_date_start().

GcalEvent implements GInitable, and creating it possibly can generate an error. At the moment, the only error that can be generate is GCAL_EVENT_ERROR_INVALID_START_DATE.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
GcalEvent *event;
GError *error;

error = NULL;
event = gcal_event_new (source, component, &error);

if (error)
  {
    g_warning ("Error creating event: %s", error->message);
    g_clear_error (&error);
    return;
  }

...

Functions

gcal_event_error_quark ()

GQuark
gcal_event_error_quark (void);

gcal_event_new ()

GcalEvent *
gcal_event_new (ESource *source,
                ECalComponent *component,
                GError **error);

Creates a new event which belongs to source and is represented by component . New events will have a NULL source .

Parameters

source

an ESource.

[nullable]

component

a ECalComponent

 

error

return location for a GError.

[nullable]

Returns

a GcalEvent.

[transfer full][nullable]


gcal_event_get_all_day ()

gboolean
gcal_event_get_all_day (GcalEvent *self);

Retrieves whether the event is all day or not.

Parameters

self

a GcalEvent

 

Returns

TRUE if self is all day, FALSE otherwise.


gcal_event_set_all_day ()

void
gcal_event_set_all_day (GcalEvent *self,
                        gboolean all_day);

Sets the GcalEvent ::all-day property.

Parameters

self

a GcalEvent

 

all_day

whether the event is all day or not

 

gcal_event_get_color ()

GdkRGBA *
gcal_event_get_color (GcalEvent *self);

Retrieves the color of the event.

Parameters

self

a GcalEvent

 

Returns

a GdkRGBA.

[transfer none]


gcal_event_set_color ()

void
gcal_event_set_color (GcalEvent *self,
                      GdkRGBA *color);

Sets the color of the event, which is passed to the parent ESource.

Parameters

self

a GcalEvent

 

color

a GdkRGBA

 

gcal_event_get_component ()

ECalComponent *
gcal_event_get_component (GcalEvent *self);

Retrieves the internal component of the event.

Parameters

self

a GcalEvent

 

Returns

an ECalComponent.

[transfer none]


gcal_event_get_date_end ()

GDateTime *
gcal_event_get_date_end (GcalEvent *self);

Retrieves the end date of self . If the component doesn't have an end date, then the returned date is the same of gcal_event_get_date_start().

Parameters

self

a GcalEvent

 

Returns

a GDateTime.

[transfer none]


gcal_event_set_date_end ()

void
gcal_event_set_date_end (GcalEvent *self,
                         GDateTime *dt);

Sets the end date as dt .

Parameters

self

a GcalEvent

 

dt

a GDateTime

 

gcal_event_get_date_start ()

GDateTime *
gcal_event_get_date_start (GcalEvent *self);

Retrieves the start date of self .

Parameters

self

a GcalEvent

 

Returns

a GDateTime.

[transfer none]


gcal_event_set_date_start ()

void
gcal_event_set_date_start (GcalEvent *self,
                           GDateTime *dt);

Sets the start date as dt .

Parameters

self

a GcalEvent

 

dt

a GDateTime

 

gcal_event_get_description ()

const gchar *
gcal_event_get_description (GcalEvent *self);

Retrieves the description of self .

Returns

the description of the event.

[transfer none]


gcal_event_set_description ()

void
gcal_event_set_description (GcalEvent *self,
                            const gchar *description);

Sets the description of the event.

Parameters

self

a GcalEvent

 

description

the new description of the event.

[nullable]

gcal_event_has_alarms ()

gboolean
gcal_event_has_alarms (GcalEvent *self);

Retrieves whether the event has alarms or not.

Parameters

self

a GcalEvent

 

Returns

TRUE if event has alarms, FALSE otherwise.


gcal_event_get_alarms ()

GList *
gcal_event_get_alarms (GcalEvent *self);

Retrieves the alarms available for self .

Parameters

self

a GcalEvent

 

Returns

a GList of ECalComponentAlarm.

[transfer full]


gcal_event_add_alarm ()

void
gcal_event_add_alarm (GcalEvent *self,
                      guint type,
                      gboolean has_sound);

Adds an alarm to self that triggers type minutes before the event's start date.

If there's already an alarm for type , it'll be replaced.

Parameters

self

a GcalEvent

 

type

the minutes before the start date to trigger the alarm

 

has_sound

whether the alarm plays a sound or not

 

gcal_event_remove_alarm ()

void
gcal_event_remove_alarm (GcalEvent *self,
                         guint type);

Removes an alarm from self that triggers type minutes before the event's start date.

If there's no alarm set for type , nothing happens.

Parameters

self

a GcalEvent

 

type

the minutes before the start date to trigger the alarm

 

gcal_event_get_location ()

const gchar *
gcal_event_get_location (GcalEvent *self);

Retrieves the location of the event.

Parameters

self

a GcalEvent

 

Returns

the location of the event.

[transfer none]


gcal_event_set_location ()

void
gcal_event_set_location (GcalEvent *self,
                         const gchar *location);

Sets the location of the event.

Parameters

self

a GcalEvent

 

location

the new location of the event.

[nullable]

gcal_event_get_source ()

ESource *
gcal_event_get_source (GcalEvent *self);

Retrieves the source of the event.

Parameters

self

a GcalEvent

 

Returns

an ESource.

[nullable]


gcal_event_set_source ()

void
gcal_event_set_source (GcalEvent *self,
                       ESource *source);

Sets the source of this event. The color of the event is automatically tied with the source's color.

The source should only be set once.

Parameters

self

a GcalEvent

 

source

an ESource

 

gcal_event_get_summary ()

const gchar *
gcal_event_get_summary (GcalEvent *self);

Retrieves the summary of this event.

Parameters

self

a GcalEvent

 

Returns

the summary of the event.

[transfer none]


gcal_event_set_summary ()

void
gcal_event_set_summary (GcalEvent *self,
                        const gchar *summary);

Sets the summary of event .

Parameters

event

a GcalEvent

 

summary

the new summary of event .

[nullable]

gcal_event_get_uid ()

const gchar *
gcal_event_get_uid (GcalEvent *self);

Retrieves the unique identifier of the event. The UID consists of '[source id]:[event id]:[recurrency id]'. If there's no recurrency assigned, the last field is ignored.

Parameters

self

a GcalEvent

 

Returns

the unique identifier of the event.

[transfer none]


gcal_event_is_multiday ()

gboolean
gcal_event_is_multiday (GcalEvent *self);

Whether the event visibly spans more than one day in the calendar.

This function can return different values for the same event depending on your timezone. For example, an event that spans [ 02:00, 22:00 ) +0000 would assume the following values:

1
2
3
4
D-1            D            D+1
-0600 [         ---][-------     ][            ] (multiday)
+0000 [            ][ ---------- ][            ] (single day)
+0800 [            ][     -------][---         ] (multiday)

Parameters

self

a GcalEvent

 

Returns

TRUE if self spans more than 1 day, FALSE otherwise.


gcal_event_compare ()

gint
gcal_event_compare (GcalEvent *event1,
                    GcalEvent *event2);

Compare event1 and event2 . It compares the start dates of the events and, when they have the same date (time is ignored), the GcalEvent ::all-day is the tiebreaker criteria.

Events with equal start dates are sorted by the length.

Parameters

event1

a GcalEvent

 

event2

a GcalEvent

 

Returns

1, 0 or -1 if event1 is, respectively, lower, equal or greater than event2 .


gcal_event_compare_with_current ()

gint
gcal_event_compare_with_current (GcalEvent *event1,
                                 GcalEvent *event2,
                                 time_t *current_time);

Compares event1 and event2 related to current_time ; the closest an event is from current_time , the more priority it has.

Parameters

event1

a GcalEvent

 

event2

a GcalEvent

 

current_time

the current time

 

Returns

-1, 0 and 1 if event1 is, respectively, farther, equal or closer from current_time relative to event2 .

Types and Values

enum GcalEventError

Errors that GcalEvent can generate.

Members

GCAL_EVENT_ERROR_INVALID_START_DATE

indicated an invalid start date

 

GCAL_EVENT_ERROR

#define GCAL_EVENT_ERROR gcal_event_error_quark ()

GCAL_TYPE_EVENT

#define GCAL_TYPE_EVENT (gcal_event_get_type())

GcalEvent

typedef struct _GcalEvent GcalEvent;

Property Details

The “all-day” property

  “all-day”                  gboolean

Whether the event is all day or not.

Flags: Read / Write

Default value: FALSE


The “color” property

  “color”                    GdkRGBA *

The color of the event.

Flags: Read / Write


The “component” property

  “component”                ECalComponent *

The ECalComponent of the event.

Flags: Read / Write / Construct Only


The “date-end” property

  “date-end”                 GDateTime *

The end date of the event.

Flags: Read / Write


The “date-start” property

  “date-start”               GDateTime *

The start date of the event.

Flags: Read / Write


The “description” property

  “description”              gchar *

The description of the event.

Flags: Read / Write

Default value: ""


The “has-recurrence” property

  “has-recurrence”           gboolean

Whether the event has recurrence or not.

Flags: Read

Default value: FALSE


The “location” property

  “location”                 gchar *

The location of the event.

Flags: Read / Write

Default value: ""


The “recurrence” property

  “recurrence”               GcalRecurrence *

The recurrence property of the event.

Flags: Read / Write


The “source” property

  “source”                   ESource *

The ESource this event belongs to.

Flags: Read / Write / Construct


The “summary” property

  “summary”                  gchar *

The summary of the event.

Flags: Read / Write

Default value: ""


The “timezone” property

  “timezone”                 GTimeZone *

The timezone of the event.

Flags: Read / Write


The “uid” property

  “uid”                      gchar *

The unique identifier of the event.

Flags: Read

Default value: ""

See Also

GcalEventWidget,GcalManager