GcalEvent: GNOME Calendar Reference Manual

## GcalEvent GcalEvent — A class that represents an event |

## Stability Level

Unstable, unless otherwise indicated

## Functions

GQuark | gcal_event_error_quark ()
GcalEvent * | gcal_event_new ()
gboolean | gcal_event_get_all_day ()
void | gcal_event_set_all_day ()
GdkRGBA * | gcal_event_get_color ()
void | gcal_event_set_color ()
ECalComponent * | gcal_event_get_component ()
GDateTime * | gcal_event_get_date_end ()
void | gcal_event_set_date_end ()
GDateTime * | gcal_event_get_date_start ()
void | gcal_event_set_date_start ()
const gchar * | gcal_event_get_description ()
void | gcal_event_set_description ()
gboolean | gcal_event_has_alarms ()
GList * | gcal_event_get_alarms ()
void | gcal_event_add_alarm ()
void | gcal_event_remove_alarm ()
const gchar * | gcal_event_get_location ()
void | gcal_event_set_location ()
ESource * | gcal_event_get_source ()
void | gcal_event_set_source ()
const gchar * | gcal_event_get_summary ()
void | gcal_event_set_summary ()
const gchar * | gcal_event_get_uid ()
gboolean | gcal_event_is_multiday ()
gint | gcal_event_compare ()
gint | gcal_event_compare_with_current ()

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

enum | GcalEventError
#define | GCAL_EVENT_ERROR
#define | GCAL_TYPE_EVENT
| GcalEvent

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