path: root/doc/devel/calendar/cal-util/tmpl/cal-component.sgml

<!-- ##### 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>
    &ldquo;Interoperable.&rdquo;  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: 
@CAL_COMPONENT_EVENT: 
@CAL_COMPONENT_TODO: 
@CAL_COMPONENT_JOURNAL: 
@CAL_COMPONENT_FREEBUSY: 
@CAL_COMPONENT_TIMEZONE: 

<!-- ##### 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: 
@CAL_COMPONENT_FIELD_CLASSIFICATION: 
@CAL_COMPONENT_FIELD_COMPLETED: 
@CAL_COMPONENT_FIELD_DTEND: 
@CAL_COMPONENT_FIELD_DTSTART: 
@CAL_COMPONENT_FIELD_DUE: 
@CAL_COMPONENT_FIELD_GEO: 
@CAL_COMPONENT_FIELD_PERCENT: 
@CAL_COMPONENT_FIELD_PRIORITY: 
@CAL_COMPONENT_FIELD_SUMMARY: 
@CAL_COMPONENT_FIELD_TRANSPARENCY: 
@CAL_COMPONENT_FIELD_URL: 
@CAL_COMPONENT_FIELD_HAS_ALARMS: 
@CAL_COMPONENT_FIELD_ICON: 
@CAL_COMPONENT_FIELD_COMPLETE: 
@CAL_COMPONENT_FIELD_RECURRING: 
@CAL_COMPONENT_FIELD_OVERDUE: 
@CAL_COMPONENT_FIELD_COLOR: 
@CAL_COMPONENT_FIELD_NUM_FIELDS: 

<!-- ##### ENUM CalComponentClassification ##### -->
  <para>
    Values for the access classification property of a calendar
    component.
  </para>

@CAL_COMPONENT_CLASS_NONE: 
@CAL_COMPONENT_CLASS_PUBLIC: 
@CAL_COMPONENT_CLASS_PRIVATE: 
@CAL_COMPONENT_CLASS_CONFIDENTIAL: 
@CAL_COMPONENT_CLASS_UNKNOWN: 

<!-- ##### 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: 
@CAL_COMPONENT_PERIOD_DURATION: 

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

</para>

@comp: 
@categories: 


<!-- ##### FUNCTION cal_component_set_categories ##### -->
<para>

</para>

@comp: 
@categories: 


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