aboutsummaryrefslogtreecommitdiffstats
path: root/help/devel/calendar/alarm-generation.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'help/devel/calendar/alarm-generation.sgml')
-rw-r--r--help/devel/calendar/alarm-generation.sgml87
1 files changed, 86 insertions, 1 deletions
diff --git a/help/devel/calendar/alarm-generation.sgml b/help/devel/calendar/alarm-generation.sgml
index 60bc78343e..77d35258da 100644
--- a/help/devel/calendar/alarm-generation.sgml
+++ b/help/devel/calendar/alarm-generation.sgml
@@ -41,7 +41,92 @@
<title>Generating trigger instances</title>
<para>
-
+ Generating absolute triggers is trivial; you just use the date
+ and time they specify. However, relative triggers are
+ associated to recurrence instances, so in order to generate
+ trigger instances we must generate the corresponding
+ recurrence instances and compute the trigger times based on
+ those.
+ </para>
+
+ <para>
+ Since relative triggers are specified as occurring a certain
+ amount of time before or after each of a calendar component's
+ recurrence instances, we can compute a trigger time by adding
+ or subtracting that amount of time to the corresponding
+ recurrence instance's time.
+ </para>
+
+ <para>
+ Recurrence instances are generated by specifying a range of
+ time and asking the Wombat to generate the instances that
+ occur within that range. We shall see that the range of time
+ in which instances occur is not necessarily the same range of
+ time in which those instances' alarm triggers occur.
+ </para>
+
+ <para>
+ Consider an alarm that is set to trigger 10 minutes before the
+ start time of an event's occurrence, that is, the trigger has
+ an offset of -10 minutes. Say this event recurs every hour at
+ 5 minutes past the hour: it would occur at 1:05, 2:05, 3:05,
+ etc.; the corresponding triggers would occur at 12:55, 1:55,
+ 2:55, etc. If we wish to compute the alarm triggers that
+ occur between 4:00 and 6:00 (which would be at 4:55 and 5:55),
+ then we cannot just generate recurrence instances between 4:00
+ and 6:00 because we will miss the 6:05 occurrence which
+ corresponds to the 5:55 trigger.
+ </para>
+
+ <para>
+ The solution is to expand the range of time on both sides to
+ fit the relative triggers that have the largest time periods.
+ If a trigger's offset is negative, like the -10 minutes in the
+ example above, then we must expand the
+ <emphasis>end</emphasis> of the time range: in the case above,
+ the range's ending time of 6:00 must be grown by 10 minutes to
+ 6:10 so that the last recurrence instance will be that of
+ 6:05; computing the trigger's offset we will get the 5:55
+ trigger, which is what we wanted. For triggers with positive
+ offsets, like if an alarm were to trigger 20 minutes after an
+ event's occurrence, we must expand the
+ <emphasis>start</emphasis> of the time range in an analogous
+ way, by subtracting the time offset from it.
+ </para>
+
+ <para>
+ Again, absolute triggers need no special computation. We can
+ just see if the trigger time is within the requested range of
+ time, and if so, we take that trigger occurrence into account
+ for the final result.
+ </para>
+ </sect1>
+
+ <sect1 id="alarm-trigger-generation-code">
+ <title>Alarm trigger generation code</title>
+
+ <para>
+ The main function to generate alarm trigger instances is
+ <function>generate_alarms_for_comp()</function> in
+ <filename>evolution/calendar/pcs/cal-backend-file.c</filename>.
+ This function calls <function>compute_alarm_range()</function>
+ to expand the specified range of time in the way described in
+ the previous section. It then generates the instances for
+ relative alarm triggers inside the
+ <function>add_alarm_occurrences_cb()</function> callback,
+ which is used by
+ <function>cal_recur_generate_instances()</function> with the
+ expanded range of time. The callback goes through all of the
+ calendar component's relative alarm triggers and adds the
+ trigger offsets to the occurrence's time; the results are
+ added as <structname>CalAlarmInstance</structname> structures
+ to the final list of trigger instances. Finally,
+ <function>generate_alarms_for_comp()</function> calls
+ <function>generate_absolute_triggers()</function>, which
+ simply adds the instances for absolute alarm triggers; these
+ are the absolute times that are within the time range that was
+ requested originally. In the very end, the list of instances
+ is sorted to produce nicer results.
</para>
</sect1>
</chapter>