![]() |
![]() |
![]() |
libjana Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Prerequisites |
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);
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.
typedef struct { JanaRecurrenceType type; gint interval; gboolean week_days[7]; gboolean by_date; JanaTime * end; } JanaRecurrence;
This struct specifies a particular recurrence.
JanaRecurrenceType |
The type of recurrence. |
gint |
The interval of the recurrence, where 1 is 'every', 2 is 'every other', 3 is 'every third', etc. |
gboolean |
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 |
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 * |
The ending time for the recurrence, or NULL for indefinite recurrences
|
typedef enum { JANA_RECURRENCE_DAILY, JANA_RECURRENCE_WEEKLY, JANA_RECURRENCE_MONTHLY, JANA_RECURRENCE_YEARLY, } JanaRecurrenceType;
Enum values for different types of recurrence.
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() .
|
JanaRecurrence * jana_recurrence_copy (JanaRecurrence *recurrence);
Creates a copy of a JanaRecurrence.
|
A JanaRecurrence |
Returns : |
A newly allocated copy of recurrence , to be freed with
jana_recurrence_free() .
|
void jana_recurrence_free (JanaRecurrence *recurrence);
Frees the memory associated with recurrence
. If recurrence
is NULL
,
does nothing.
|
A JanaRecurrence |
void jana_exceptions_free (GList *exceptions);
Frees a list of exceptions. See jana_event_get_exceptions()
.
|
A list of exceptions, as returned by
jana_event_get_exceptions()
|
gchar * jana_event_get_summary (JanaEvent *self);
Retrieves the summary associated with the event.
|
A JanaEvent |
Returns : |
A newly allocated string, containing the summary.
See jana_event_set_summary() .
|
gchar * jana_event_get_description (JanaEvent *self);
Retrieves the description associated with the event.
|
A JanaEvent |
Returns : |
A newly allocated string, containing the description. See
jana_event_set_description() .
|
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()
.
|
A JanaEvent |
Returns : |
A newly allocated string, containing the location. |
JanaTime * jana_event_get_start (JanaEvent *self);
Retrieves the time at which the event starts. See jana_event_set_start()
.
JanaTime * jana_event_get_end (JanaEvent *self);
Retrieves the time at which the event ends. See jana_event_set_end()
.
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()
.
|
A JanaEvent |
Returns : |
A newly allocated, NULL -terminated array of strings, or NULL .
|
gboolean jana_event_supports_alarm (JanaEvent *self);
Determines whether the event supports setting an alarm.
|
A JanaEvent |
Returns : |
TRUE if the event supports setting an alarm, FALSE otherwise.
|
gboolean jana_event_has_alarm (JanaEvent *self);
Determines whether the event has an alarm set on it.
|
A JanaEvent |
Returns : |
TRUE if the event has an alarm set, FALSE otherwise.
|
JanaTime * jana_event_get_alarm_time (JanaEvent *self);
Retrieves the alarm time set on the event. See jana_event_set_alarm_time()
.
gboolean jana_event_supports_recurrence (JanaEvent *self);
Determines whether the event supports setting a recurrence.
|
A JanaEvent |
Returns : |
TRUE if the event supports setting a recurrence, FALSE otherwise.
|
gboolean jana_event_has_recurrence (JanaEvent *self);
Determines whether the event has a set recurrence.
|
A JanaEvent |
Returns : |
TRUE if the event has a set recurrence, FALSE otherwise.
|
JanaRecurrence * jana_event_get_recurrence (JanaEvent *self);
Retrieves the recurrence description set on the event.
|
A JanaEvent |
Returns : |
A newly allocated JanaRecurrence, or NULL if there is no
set recurrence. See jana_event_get_recurrence() .
|
gboolean jana_event_supports_exceptions (JanaEvent *self);
Determines whether the event supports setting an exceptions list.
|
A JanaEvent |
Returns : |
TRUE if the event supports setting exceptions, FALSE otherwise.
|
gboolean jana_event_has_exceptions (JanaEvent *self);
Determines whether the event has an exceptions list.
|
A JanaEvent |
Returns : |
TRUE if the event has an exceptions list, FALSE otherwise.
|
GList * jana_event_get_exceptions (JanaEvent *self);
Retrieves the event's exceptions list. See jana_event_set_exceptions()
.
|
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() .
|
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.
|
A JanaEvent |
|
A summary string |
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.
|
A JanaEvent |
|
A description string |
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()
).
|
A JanaEvent |
|
A location string |
void jana_event_set_start (JanaEvent *self, JanaTime *start);
Sets the event's starting time.
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.
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()
.
|
A JanaEvent |
|
A NULL -terminated array of strings, or NULL
|
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()
.
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()
.
|
A JanaEvent |
|
A JanaRecurrence, or NULL
|
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()
.