blob: c429e22a9cb6ebd89e143a320fc4452eb23bb34a (
plain) (
tree)
|
|
<!-- ##### SECTION Title ##### -->
CalComponent
<!-- ##### SECTION Short_Description ##### -->
RFC 2445 iCalendar component object.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #CalComponent object provides a wrapper over the &libical;
functions for manipulating calendar components. #CalComponent
presents a GTK+-like interface to calendar components according to
RFC 2445.
</para>
<para>
While &libical; supports almost all of the features of the
iCalendar RFCs, applications are normally not interested in all
the mindless gunk that is there. Still, applications should do
their best not to drop extension fields from calendar components
or any other extra information they do not support (including
standard fields they are not interested in). The #CalComponent
object provides a wrapper over
<structname>icalcomponent</structname> structures from &libical;
so that no information in them will be lost even if the
application is not designed to handle it. Also, #CalComponent
provides a higher-level API to many of the &libical; operations so
as to make it less painful to deal with iCalendar components.
</para>
<para>
A #CalComponent object starts out empty. It must be initialized
from an existing <structname>icalcomponent</structname> structure
by using the cal_component_set_icalcomponent() function, or from a
completely new data by specifying the desired component type to
the cal_component_set_new_vtype() function.
</para>
<para>
#CalComponent will create an internal map of the properties in the
<structname>icalcomponent</structname> structure and then allow
random access to them via the #CalComponent API functions;
normally the &libical; API would have to be used by creating many
iterators and other unpleasant constructs. #CalComponent keeps
handles to the properties it scanned from the
<structname>icalcomponent</structname> and will let the parent
application modify them at any time without having to do any
iteration.
</para>
<para>
Eventually a #CalComponent may be turned into the RFC 2445 string
representation of an iCalendar component by using the
cal_component_get_as_string() function. Applications can then
transfer this interoperable
<footnote>
<para>
“Interoperable.” Heavens, I love that word.
</para>
</footnote>
string to other programs that deal with iCalendar.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### MACRO CAL_COMPONENT ##### -->
<para>
Casts a #GtkObject to a #CalComponent.
</para>
@obj: A GTK+ object.
<!-- ##### ENUM CalComponentVType ##### -->
<para>
Calendar component types as defined by RFC 2445. These values can
be used to create a new calendar component by passing them to the
cal_component_set_new_vtype() function. They are also the return
value of the cal_component_get_vtype() function. The only time
the @CAL_COMPONENT_NO_TYPE value is used is when querying the
vtype of an uninitialized #CalComponent.
</para>
@CAL_COMPONENT_NO_TYPE: Returned from cal_component_get_vtype() to
indicate an uninitialized #CalComponent object.
@CAL_COMPONENT_EVENT: Indicates a VEVENT component.
@CAL_COMPONENT_TODO: Indicates a VTODO component.
@CAL_COMPONENT_JOURNAL: Indicates a VJOURNAL component.
@CAL_COMPONENT_FREEBUSY: Indicates a VFREEBUSY component.
@CAL_COMPONENT_TIMEZONE: Indicates a VTIMEZOME component.
<!-- ##### ENUM CalComponentField ##### -->
<para>
These values are used as identifiers for #ETable columns. These
are used by the calendar GUI code in &Evolution;.
</para>
@CAL_COMPONENT_FIELD_CATEGORIES: Component's list of categories.
@CAL_COMPONENT_FIELD_CLASSIFICATION: Component's classification.
@CAL_COMPONENT_FIELD_COMPLETED: Component's completion date.
@CAL_COMPONENT_FIELD_DTEND: Component's ending date.
@CAL_COMPONENT_FIELD_DTSTART: Component's starting date.
@CAL_COMPONENT_FIELD_DUE: Component's due date.
@CAL_COMPONENT_FIELD_GEO: Component's geographical position.
@CAL_COMPONENT_FIELD_PERCENT: Component's percent completed value.
@CAL_COMPONENT_FIELD_PRIORITY: Component's priority.
@CAL_COMPONENT_FIELD_SUMMARY: Component's summary.
@CAL_COMPONENT_FIELD_TRANSPARENCY: Component's transparency value.
@CAL_COMPONENT_FIELD_URL: Component's URL.
@CAL_COMPONENT_FIELD_HAS_ALARMS: Whether the component has any alarms.
@CAL_COMPONENT_FIELD_ICON: Which icon to use for the component.
@CAL_COMPONENT_FIELD_COMPLETE: Whether the component has been completed.
@CAL_COMPONENT_FIELD_RECURRING: Whether the component has any recurrences.
@CAL_COMPONENT_FIELD_OVERDUE: Whether the component is overdue.
@CAL_COMPONENT_FIELD_COLOR: Which color to use for the component.
@CAL_COMPONENT_FIELD_NUM_FIELDS: Total number of enumerated fields.
<!-- ##### ENUM CalComponentClassification ##### -->
<para>
Values for the access classification property of a calendar
component.
</para>
@CAL_COMPONENT_CLASS_NONE: Indicates that no access classification has
been set for the corresponding component.
@CAL_COMPONENT_CLASS_PUBLIC: Public access.
@CAL_COMPONENT_CLASS_PRIVATE: Private access.
@CAL_COMPONENT_CLASS_CONFIDENTIAL: Confidential access.
@CAL_COMPONENT_CLASS_UNKNOWN: Unknown access classification value,
used when &libical; returns something #CalComponent does not know
about.
<!-- ##### TYPEDEF CalComponentDateTime ##### -->
<para>
This structure defines a date and time value.
</para>
<!-- ##### ENUM CalComponentPeriodType ##### -->
<para>
Defines how a period of time is specified.
</para>
@CAL_COMPONENT_PERIOD_DATETIME: Indicates that the period is specified
by starting and ending date/time values.
@CAL_COMPONENT_PERIOD_DURATION: Indicates that the period is specified
as a starding date/time and a duration value.
<!-- ##### TYPEDEF CalComponentPeriod ##### -->
<para>
This structure defines a period of time.
</para>
<!-- ##### TYPEDEF CalComponentText ##### -->
<para>
This structure defines the value of a text property that may have
an alternate representation parameter.
</para>
<!-- ##### ENUM CalComponentTransparency ##### -->
<para>
</para>
@CAL_COMPONENT_TRANSP_NONE:
@CAL_COMPONENT_TRANSP_TRANSPARENT:
@CAL_COMPONENT_TRANSP_OPAQUE:
@CAL_COMPONENT_TRANSP_UNKNOWN:
<!-- ##### FUNCTION cal_component_gen_uid ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION cal_component_new ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION cal_component_clone ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_set_new_vtype ##### -->
<para>
</para>
@comp:
@type:
<!-- ##### FUNCTION cal_component_set_icalcomponent ##### -->
<para>
</para>
@comp:
@icalcomp:
@Returns:
<!-- ##### FUNCTION cal_component_get_icalcomponent ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_get_vtype ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_get_as_string ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_commit_sequence ##### -->
<para>
</para>
@comp:
<!-- ##### FUNCTION cal_component_get_uid ##### -->
<para>
</para>
@comp:
@uid:
<!-- ##### FUNCTION cal_component_set_uid ##### -->
<para>
</para>
@comp:
@uid:
<!-- ##### FUNCTION cal_component_get_categories_list ##### -->
<para>
</para>
@comp:
@categ_list:
<!-- ##### FUNCTION cal_component_set_categories_list ##### -->
<para>
</para>
@comp:
@categ_list:
<!-- ##### FUNCTION cal_component_get_classification ##### -->
<para>
</para>
@comp:
@classif:
<!-- ##### FUNCTION cal_component_set_classification ##### -->
<para>
</para>
@comp:
@classif:
<!-- ##### FUNCTION cal_component_get_comment_list ##### -->
<para>
</para>
@comp:
@text_list:
<!-- ##### FUNCTION cal_component_set_comment_list ##### -->
<para>
</para>
@comp:
@text_list:
<!-- ##### FUNCTION cal_component_get_completed ##### -->
<para>
</para>
@comp:
@t:
<!-- ##### FUNCTION cal_component_set_completed ##### -->
<para>
</para>
@comp:
@t:
<!-- ##### FUNCTION cal_component_get_created ##### -->
<para>
</para>
@comp:
@t:
<!-- ##### FUNCTION cal_component_set_created ##### -->
<para>
</para>
@comp:
@t:
<!-- ##### FUNCTION cal_component_get_description_list ##### -->
<para>
</para>
@comp:
@text_list:
<!-- ##### FUNCTION cal_component_set_description_list ##### -->
<para>
</para>
@comp:
@text_list:
<!-- ##### FUNCTION cal_component_get_dtend ##### -->
<para>
</para>
@comp:
@dt:
<!-- ##### FUNCTION cal_component_set_dtend ##### -->
<para>
</para>
@comp:
@dt:
<!-- ##### FUNCTION cal_component_get_dtstamp ##### -->
<para>
</para>
@comp:
@t:
<!-- ##### FUNCTION cal_component_set_dtstamp ##### -->
<para>
</para>
@comp:
@t:
<!-- ##### FUNCTION cal_component_get_dtstart ##### -->
<para>
</para>
@comp:
@dt:
<!-- ##### FUNCTION cal_component_set_dtstart ##### -->
<para>
</para>
@comp:
@dt:
<!-- ##### FUNCTION cal_component_get_due ##### -->
<para>
</para>
@comp:
@dt:
<!-- ##### FUNCTION cal_component_set_due ##### -->
<para>
</para>
@comp:
@dt:
<!-- ##### FUNCTION cal_component_get_exdate_list ##### -->
<para>
</para>
@comp:
@exdate_list:
<!-- ##### FUNCTION cal_component_set_exdate_list ##### -->
<para>
</para>
@comp:
@exdate_list:
<!-- ##### FUNCTION cal_component_has_exdates ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_get_exrule_list ##### -->
<para>
</para>
@comp:
@recur_list:
<!-- ##### FUNCTION cal_component_get_exrule_property_list ##### -->
<para>
</para>
@comp:
@recur_list:
<!-- ##### FUNCTION cal_component_set_exrule_list ##### -->
<para>
</para>
@comp:
@recur_list:
<!-- ##### FUNCTION cal_component_has_exrules ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_has_exceptions ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_get_geo ##### -->
<para>
</para>
@comp:
@geo:
<!-- ##### FUNCTION cal_component_set_geo ##### -->
<para>
</para>
@comp:
@geo:
<!-- ##### FUNCTION cal_component_get_last_modified ##### -->
<para>
</para>
@comp:
@t:
<!-- ##### FUNCTION cal_component_set_last_modified ##### -->
<para>
</para>
@comp:
@t:
<!-- ##### FUNCTION cal_component_get_percent ##### -->
<para>
</para>
@comp:
@percent:
<!-- ##### FUNCTION cal_component_set_percent ##### -->
<para>
</para>
@comp:
@percent:
<!-- ##### FUNCTION cal_component_get_priority ##### -->
<para>
</para>
@comp:
@priority:
<!-- ##### FUNCTION cal_component_set_priority ##### -->
<para>
</para>
@comp:
@priority:
<!-- ##### FUNCTION cal_component_get_rdate_list ##### -->
<para>
</para>
@comp:
@period_list:
<!-- ##### FUNCTION cal_component_set_rdate_list ##### -->
<para>
</para>
@comp:
@period_list:
<!-- ##### FUNCTION cal_component_has_rdates ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_get_rrule_list ##### -->
<para>
</para>
@comp:
@recur_list:
<!-- ##### FUNCTION cal_component_get_rrule_property_list ##### -->
<para>
</para>
@comp:
@recur_list:
<!-- ##### FUNCTION cal_component_set_rrule_list ##### -->
<para>
</para>
@comp:
@recur_list:
<!-- ##### FUNCTION cal_component_has_rrules ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_has_recurrences ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_get_sequence ##### -->
<para>
</para>
@comp:
@sequence:
<!-- ##### FUNCTION cal_component_set_sequence ##### -->
<para>
</para>
@comp:
@sequence:
<!-- ##### FUNCTION cal_component_get_status ##### -->
<para>
</para>
@comp:
@status:
<!-- ##### FUNCTION cal_component_set_status ##### -->
<para>
</para>
@comp:
@status:
<!-- ##### FUNCTION cal_component_get_summary ##### -->
<para>
</para>
@comp:
@summary:
<!-- ##### FUNCTION cal_component_set_summary ##### -->
<para>
</para>
@comp:
@summary:
<!-- ##### FUNCTION cal_component_get_transparency ##### -->
<para>
</para>
@comp:
@transp:
<!-- ##### FUNCTION cal_component_set_transparency ##### -->
<para>
</para>
@comp:
@transp:
<!-- ##### FUNCTION cal_component_get_url ##### -->
<para>
</para>
@comp:
@url:
<!-- ##### FUNCTION cal_component_set_url ##### -->
<para>
</para>
@comp:
@url:
<!-- ##### FUNCTION cal_component_free_categories_list ##### -->
<para>
</para>
@categ_list:
<!-- ##### FUNCTION cal_component_free_datetime ##### -->
<para>
</para>
@dt:
<!-- ##### FUNCTION cal_component_free_exdate_list ##### -->
<para>
</para>
@exdate_list:
<!-- ##### FUNCTION cal_component_free_geo ##### -->
<para>
</para>
@geo:
<!-- ##### FUNCTION cal_component_free_icaltimetype ##### -->
<para>
</para>
@t:
<!-- ##### FUNCTION cal_component_free_percent ##### -->
<para>
</para>
@percent:
<!-- ##### FUNCTION cal_component_free_priority ##### -->
<para>
</para>
@priority:
<!-- ##### FUNCTION cal_component_free_period_list ##### -->
<para>
</para>
@period_list:
<!-- ##### FUNCTION cal_component_free_recur_list ##### -->
<para>
</para>
@recur_list:
<!-- ##### FUNCTION cal_component_free_sequence ##### -->
<para>
</para>
@sequence:
<!-- ##### FUNCTION cal_component_free_text_list ##### -->
<para>
</para>
@text_list:
<!-- ##### STRUCT CalComponentAlarm ##### -->
<para>
</para>
<!-- ##### TYPEDEF CalAlarmInstance ##### -->
<para>
</para>
<!-- ##### TYPEDEF CalComponentAlarms ##### -->
<para>
</para>
<!-- ##### ENUM CalAlarmAction ##### -->
<para>
</para>
@CAL_ALARM_NONE:
@CAL_ALARM_AUDIO:
@CAL_ALARM_DISPLAY:
@CAL_ALARM_EMAIL:
@CAL_ALARM_PROCEDURE:
@CAL_ALARM_UNKNOWN:
<!-- ##### ENUM CalAlarmTriggerType ##### -->
<para>
</para>
@CAL_ALARM_TRIGGER_NONE:
@CAL_ALARM_TRIGGER_RELATIVE_START:
@CAL_ALARM_TRIGGER_RELATIVE_END:
@CAL_ALARM_TRIGGER_ABSOLUTE:
<!-- ##### TYPEDEF CalAlarmTrigger ##### -->
<para>
</para>
<!-- ##### FUNCTION cal_component_has_alarms ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_get_alarm_uids ##### -->
<para>
</para>
@comp:
@Returns:
<!-- ##### FUNCTION cal_component_get_alarm ##### -->
<para>
</para>
@comp:
@auid:
@Returns:
<!-- ##### FUNCTION cal_component_alarm_free ##### -->
<para>
</para>
@alarm:
<!-- ##### FUNCTION cal_component_alarms_free ##### -->
<para>
</para>
@alarms:
<!-- ##### FUNCTION cal_component_alarm_get_uid ##### -->
<para>
</para>
@alarm:
@Returns:
<!-- ##### FUNCTION cal_component_alarm_get_action ##### -->
<para>
</para>
@alarm:
@action:
<!-- ##### FUNCTION cal_component_alarm_set_action ##### -->
<para>
</para>
@alarm:
@action:
<!-- ##### FUNCTION cal_component_alarm_get_trigger ##### -->
<para>
</para>
@alarm:
@trigger:
<!-- ##### FUNCTION cal_component_alarm_set_trigger ##### -->
<para>
</para>
@alarm:
@trigger:
|