JanaEvent

JanaEvent — An event component interface

Functions

Types and Values

Object Hierarchy

    GBoxed
    ╰── JanaRecurrence
    GInterface
    ╰── JanaEvent

Prerequisites

JanaEvent requires GObject.

Description

JanaEvent is the interface for components that store information on calendar events. It has functions for basic event description, as well as recurrences, exceptions and alarms.

Functions

jana_recurrence_new ()

JanaRecurrence *
jana_recurrence_new ();

Creates a new JanaRecurrence. This will be an infinite, daily recurrence, with an interval of 1. All other fields will be left NULL or FALSE.

Returns

A newly allocated JanaRecurrence, to be freed with jana_recurrence_free().


jana_recurrence_copy ()

JanaRecurrence *
jana_recurrence_copy (JanaRecurrence *recurrence);

Creates a copy of a JanaRecurrence.

Parameters

recurrence

A JanaRecurrence

 

Returns

A newly allocated copy of recurrence , to be freed with jana_recurrence_free().


jana_recurrence_free ()

void
jana_recurrence_free (JanaRecurrence *recurrence);

Frees the memory associated with recurrence . If recurrence is NULL, does nothing.

Parameters

recurrence

A JanaRecurrence

 

jana_exceptions_free ()

void
jana_exceptions_free (GList *exceptions);

Frees a list of exceptions. See jana_event_get_exceptions().

Parameters

exceptions

A list of exceptions, as returned by jana_event_get_exceptions()

 

jana_event_get_summary ()

gchar *
jana_event_get_summary (JanaEvent *self);

Retrieves the summary associated with the event.

Parameters

self

A JanaEvent

 

Returns

A newly allocated string, containing the summary. See jana_event_set_summary().


jana_event_get_description ()

gchar *
jana_event_get_description (JanaEvent *self);

Retrieves the description associated with the event.

Parameters

self

A JanaEvent

 

Returns

A newly allocated string, containing the description. See jana_event_set_description().


jana_event_get_location ()

gchar *
jana_event_get_location (JanaEvent *self);

Retrieves the location associated with the event. Note that this is just a field designated for a user-specified location, and as such, is not related to time-zones and has no particular format. See jana_event_set_location().

Parameters

self

A JanaEvent

 

Returns

A newly allocated string, containing the location.


jana_event_get_start ()

JanaTime *
jana_event_get_start (JanaEvent *self);

Retrieves the time at which the event starts. See jana_event_set_start().

Parameters

self

A JanaEvent

 

Returns

A referenced JanaTime for the start of the event.


jana_event_get_end ()

JanaTime *
jana_event_get_end (JanaEvent *self);

Retrieves the time at which the event ends. See jana_event_set_end().

Parameters

self

A JanaEvent

 

Returns

A referenced JanaTime for the end of the event.


jana_event_get_categories ()

gchar **
jana_event_get_categories (JanaEvent *self);

jana_event_get_categories is deprecated and should not be used in newly-written code.

Use jana_component_get_categories() instead.

See jana_component_get_categories().

Parameters

self

A JanaEvent

 

Returns

A newly allocated, NULL-terminated array of strings, or NULL.


jana_event_supports_alarm ()

gboolean
jana_event_supports_alarm (JanaEvent *self);

Determines whether the event supports setting an alarm.

Parameters

self

A JanaEvent

 

Returns

TRUE if the event supports setting an alarm, FALSE otherwise.


jana_event_has_alarm ()

gboolean
jana_event_has_alarm (JanaEvent *self);

Determines whether the event has an alarm set on it.

Parameters

self

A JanaEvent

 

Returns

TRUE if the event has an alarm set, FALSE otherwise.


jana_event_get_alarm_time ()

JanaTime *
jana_event_get_alarm_time (JanaEvent *self);

Retrieves the alarm time set on the event. See jana_event_set_alarm_time().

Parameters

self

A JanaEvent

 

Returns

A referenced JanaTime for the alarm set on the event, or NULL if there is no alarm set.


jana_event_supports_recurrence ()

gboolean
jana_event_supports_recurrence (JanaEvent *self);

Determines whether the event supports setting a recurrence.

Parameters

self

A JanaEvent

 

Returns

TRUE if the event supports setting a recurrence, FALSE otherwise.


jana_event_has_recurrence ()

gboolean
jana_event_has_recurrence (JanaEvent *self);

Determines whether the event has a set recurrence.

Parameters

self

A JanaEvent

 

Returns

TRUE if the event has a set recurrence, FALSE otherwise.


jana_event_get_recurrence ()

JanaRecurrence *
jana_event_get_recurrence (JanaEvent *self);

Retrieves the recurrence description set on the event.

Parameters

self

A JanaEvent

 

Returns

A newly allocated JanaRecurrence, or NULL if there is no set recurrence. See jana_event_get_recurrence().


jana_event_supports_exceptions ()

gboolean
jana_event_supports_exceptions (JanaEvent *self);

Determines whether the event supports setting an exceptions list.

Parameters

self

A JanaEvent

 

Returns

TRUE if the event supports setting exceptions, FALSE otherwise.


jana_event_has_exceptions ()

gboolean
jana_event_has_exceptions (JanaEvent *self);

Determines whether the event has an exceptions list.

Parameters

self

A JanaEvent

 

Returns

TRUE if the event has an exceptions list, FALSE otherwise.


jana_event_get_exceptions ()

GList *
jana_event_get_exceptions (JanaEvent *self);

Retrieves the event's exceptions list. See jana_event_set_exceptions().

Parameters

self

A JanaEvent

 

Returns

A list of dates, as JanaTime, on which the event does not occur, or NULL if there is no set exceptions list. This list should be freed with jana_exceptions_free().


jana_event_set_summary ()

void
jana_event_set_summary (JanaEvent *self,
                        const gchar *summary);

Sets the event's summary. Ideally, a summary should be a short, one-line description of the event.

Parameters

self

A JanaEvent

 

summary

A summary string

 

jana_event_set_description ()

void
jana_event_set_description (JanaEvent *self,
                            const gchar *description);

Sets the event's description. A description can elaborate on the event's summary and include event details that do not fit, or are not appropriate in other fields.

Parameters

self

A JanaEvent

 

description

A description string

 

jana_event_set_location ()

void
jana_event_set_location (JanaEvent *self,
                         const gchar *location);

Sets the event's location. Ideally, a location should be a short, one-line summary of the event's location. A full address would be more suited to the description field (see jana_event_set_description()).

Parameters

self

A JanaEvent

 

location

A location string

 

jana_event_set_start ()

void
jana_event_set_start (JanaEvent *self,
                      JanaTime *start);

Sets the event's starting time.

Parameters

self

A JanaEvent

 

start

A JanaTime

 

jana_event_set_end ()

void
jana_event_set_end (JanaEvent *self,
                    JanaTime *end);

Sets the event's ending time. This should not occur on or before the starting time. Setting an ending time before a starting time may cause unpredictable results, depending on the implementation of JanaEvent.

Parameters

self

A JanaEvent

 

end

A JanaTime

 

jana_event_set_categories ()

void
jana_event_set_categories (JanaEvent *self,
                           const gchar **categories);

jana_event_set_categories is deprecated and should not be used in newly-written code.

Use jana_component_set_categories() instead.

See jana_component_set_categories().

Parameters

self

A JanaEvent

 

categories

A NULL-terminated array of strings, or NULL

 

jana_event_set_alarm ()

void
jana_event_set_alarm (JanaEvent *self,
                      JanaTime *time);

Sets or clears the event's alarm time. This function does nothing if the event does not support alarms. See jana_event_supports_alarm().

Parameters

self

A JanaEvent

 

time

A JanaTime, or NULL

 

jana_event_set_recurrence ()

void
jana_event_set_recurrence (JanaEvent *self,
                           const JanaRecurrence *recurrence);

Sets or clears the event's recurrence rule. This function does nothing if the event does not support recurrence. See jana_event_supports_recurrence().

Parameters

self

A JanaEvent

 

recurrence

A JanaRecurrence, or NULL

 

jana_event_set_exceptions ()

void
jana_event_set_exceptions (JanaEvent *self,
                           GList *exceptions);

Sets the event's exceptions list. For each JanaTime in exceptions , the event is considered not to occur, even if its start/end or recurrence rule would dictate otherwise. This function does nothing if the event does not support exceptions. See jana_event_supports_exceptions().

Parameters

self

A JanaEvent

 

exceptions

A list of JanaTime objects.

 

Types and Values

JanaEvent

typedef struct _JanaEvent JanaEvent;

The JanaEvent struct contains only private data.


JanaRecurrence

typedef struct {
	JanaRecurrenceType type;
	gint 			interval;
	gboolean		week_days[7];
	gboolean 		by_date;
	JanaTime *		end;
} JanaRecurrence;

This struct specifies a particular recurrence.

Members

JanaRecurrenceType type;

The type of recurrence.

 

gint interval;

The interval of the recurrence, where 1 is 'every', 2 is 'every other', 3 is 'every third', etc.

 

gboolean week_days[7];

For weekly recurrence, this indicates which days the recurrence happens on. The zeroth element in the array corresponds to a Monday and each day follow sequentially. If week_days is empty, the starting date of the recurrence is assumed to be the day to occur on. If week_days does not include the starting day but includes other days, the recurrence will occur on the starting day, then every week on the days specified in week_days after the starting day.

 

gboolean by_date;

For monthly recurrence, this indicates whether the recurrence is by day or by date (i.e. First Monday of the month, or 1st of the month). If by_date is FALSE, the day of the starting date will be used to determine which day to occur on. If the starting date is the last day in that month, the recurrence rule is treated as 'last x-day in month', as not all months have the same amount of week-days.

 

JanaTime *end;

The ending time for the recurrence, or NULL for indefinite recurrences

 

enum JanaRecurrenceType

Enum values for different types of recurrence.

Members

JANA_RECURRENCE_DAILY

A daily recurrence

 

JANA_RECURRENCE_WEEKLY

A weekly recurrence

 

JANA_RECURRENCE_MONTHLY

A monthly recurrence

 

JANA_RECURRENCE_YEARLY

A yearly recurrence

 

See Also

JanaComponent