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

<!-- ##### STRUCT CalComponentAlarm ##### -->
<para>

</para>


<!-- ##### STRUCT CalComponentPrivate ##### -->
<para>

</para>


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

</para>

@comp: 
@recur_list: 


<!-- ##### FUNCTION cal_component_set_exrule_list ##### -->
<para>

</para>

@comp: 
@recur_list: 


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

</para>

@comp: 
@recur_list: 


<!-- ##### FUNCTION cal_component_has_rrules ##### -->
<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_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_get_pilot_id ##### -->
<para>

</para>

@comp: 
@pilot_id: 


<!-- ##### FUNCTION cal_component_set_pilot_id ##### -->
<para>

</para>

@comp: 
@pilot_id: 


<!-- ##### FUNCTION cal_component_get_pilot_status ##### -->
<para>

</para>

@comp: 
@pilot_status: 


<!-- ##### FUNCTION cal_component_set_pilot_status ##### -->
<para>

</para>

@comp: 
@pilot_status: 


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


<!-- ##### ENUM CalComponentAlarmAction ##### -->
<para>

</para>

@CAL_COMPONENT_ALARM_NONE: 
@CAL_COMPONENT_ALARM_AUDIO: 
@CAL_COMPONENT_ALARM_DISPLAY: 
@CAL_COMPONENT_ALARM_EMAIL: 
@CAL_COMPONENT_ALARM_PROCEDURE: 
@CAL_COMPONENT_ALARM_UNKNOWN: 

<!-- ##### ENUM CalComponentAlarmTriggerType ##### -->
<para>

</para>

@CAL_COMPONENT_ALARM_TRIGGER_RELATIVE: 
@CAL_COMPONENT_ALARM_TRIGGER_ABSOLUTE: 

<!-- ##### ENUM CalComponentAlarmTriggerRelated ##### -->
<para>

</para>

@CAL_COMPONENT_ALARM_TRIGGER_RELATED_START: 
@CAL_COMPONENT_ALARM_TRIGGER_RELATED_END: 

<!-- ##### TYPEDEF CalComponentAlarmTrigger ##### -->
<para>

</para>


<!-- ##### FUNCTION cal_component_get_first_alarm ##### -->
<para>

</para>

@comp: 
@Returns: 


<!-- ##### FUNCTION cal_component_get_next_alarm ##### -->
<para>

</para>

@comp: 
@Returns: 


<!-- ##### FUNCTION cal_component_alarm_free ##### -->
<para>

</para>

@alarm: 


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


<!-- ##### FUNCTION cal_component_alarm_free_trigger ##### -->
<para>

</para>

@trigger: 


<!--
Local variables:
mode: sgml
sgml-parent-document: ("../../../evolution-devel-guide.sgml" "book" "refsect2" "")
End:
-->