JanaEvent

JanaEvent — An event component interface

Synopsis

                    JanaEvent;
                    JanaRecurrence;
enum                JanaRecurrenceType;
JanaRecurrence *    jana_recurrence_new                 ();
JanaRecurrence *    jana_recurrence_copy                (JanaRecurrence *recurrence);
void                jana_recurrence_free                (JanaRecurrence *recurrence);
void                jana_exceptions_free                (GList *exceptions);
gchar *             jana_event_get_summary              (JanaEvent *self);
gchar *             jana_event_get_description          (JanaEvent *self);
gchar *             jana_event_get_location             (JanaEvent *self);
JanaTime *          jana_event_get_start                (JanaEvent *self);
JanaTime *          jana_event_get_end                  (JanaEvent *self);
gchar **            jana_event_get_categories           (JanaEvent *self);
gboolean            jana_event_supports_alarm           (JanaEvent *self);
gboolean            jana_event_has_alarm                (JanaEvent *self);
JanaTime *          jana_event_get_alarm_time           (JanaEvent *self);
gboolean            jana_event_supports_recurrence      (JanaEvent *self);
gboolean            jana_event_has_recurrence           (JanaEvent *self);
JanaRecurrence *    jana_event_get_recurrence           (JanaEvent *self);
gboolean            jana_event_supports_exceptions      (JanaEvent *self);
gboolean            jana_event_has_exceptions           (JanaEvent *self);
GList *             jana_event_get_exceptions           (JanaEvent *self);
void                jana_event_set_summary              (JanaEvent *self,
                                                         const gchar *summary);
void                jana_event_set_description          (JanaEvent *self,
                                                         const gchar *description);
void                jana_event_set_location             (JanaEvent *self,
                                                         const gchar *location);
void                jana_event_set_start                (JanaEvent *self,
                                                         JanaTime *start);
void                jana_event_set_end                  (JanaEvent *self,
                                                         JanaTime *end);
void                jana_event_set_categories           (JanaEvent *self,
                                                         const gchar **categories);
void                jana_event_set_alarm                (JanaEvent *self,
                                                         JanaTime *time);
void                jana_event_set_recurrence           (JanaEvent *self,
                                                         const JanaRecurrence *recurrence);
void                jana_event_set_exceptions           (JanaEvent *self,
                                                         GList *exceptions);

Object Hierarchy

  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.

Details

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.

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

typedef enum {
	JANA_RECURRENCE_DAILY,
	JANA_RECURRENCE_WEEKLY,
	JANA_RECURRENCE_MONTHLY,
	JANA_RECURRENCE_YEARLY,
} JanaRecurrenceType;

Enum values for different types of recurrence.

JANA_RECURRENCE_DAILY

A daily recurrence

JANA_RECURRENCE_WEEKLY

A weekly recurrence

JANA_RECURRENCE_MONTHLY

A monthly recurrence

JANA_RECURRENCE_YEARLY

A yearly recurrence

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.

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.

recurrence :

A JanaRecurrence

jana_exceptions_free ()

void                jana_exceptions_free                (GList *exceptions);

Frees a list of exceptions. See jana_event_get_exceptions().

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.

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.

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().

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().

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().

self :

A JanaEvent

Returns :

A referenced JanaTime for the end of the event.

jana_event_get_categories ()

gchar **            jana_event_get_categories           (JanaEvent *self);

Warning

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().

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.

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.

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().

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.

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.

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.

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.

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.

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().

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.

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.

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()).

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.

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.

self :

A JanaEvent

end :

A JanaTime

jana_event_set_categories ()

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

Warning

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().

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().

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().

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().

self :

A JanaEvent

exceptions :

A list of JanaTime objects.

See Also

#JanaComponent