3.12 Formatting event views

"UK's Kalender" allows very detailed formatting of the event views. With system variables you can define how the table headers are labeled, how normal events, single day or multi day events are displayed, what information is shown in the tooltips and many more.

The settings for this are available from the menu under "Extras / Internal Formats...". The dialog for making this settings is described in detail in chapter 3.13.

You can also use the system variables in the description and notes of an event. This allows e.g. displaying the age of a person in a birthday reminder.

System variables for configuring the calendar views are separated in two groups, one for formatting dates and one for formatting events. Both are now described in detail.

3.12.1 Date formats

Date formats control the way dates are displayed. The date December, 12th 2002 can be displayed in the short version 12/13/2002 or the European version 12. December 2002. All visible dates can be configured just the way you like. The syntax for this is easy.

Any part of a date, like day, month or hour, has a corresponding variable. The date display results from a combination of this variables. Following variables are available:

Table 3.12.1: Date formatting codes

The date display "Friday, the 13. December 2002, 15:20" can be obtained with follwing date format: "%A, the %d. %B %Y, %H:%M". The short version "12/13/02, 3:20 PM" by the format "%m/%d/%y, %I:%M %p" accordingly.

Normally, decimal numbers like the day of the month are displayed with leading zeros. If this is not wanted, you need to enter a "#" right after the leading "%". The example above would like "%A, the %#d. %B %Y, %#H:%M" then.

Where to make these settings is described in chapter 3.13.

3.12.2 Event formats

The event display is configured similarly to the date display, but with much more possibilities. System variables for event formatting are always enclosed by a "$" character. The most simple variables consist just of these markers and the variable name.

Table 3.12.2: Simple event variables

To retrieve e.g. the notes of an event, simply write: $NOTES$.

More complex are variables for specifying dates and time periods. Starting point for these variables is always a particular event. For this event, following keywords are possible:

Table 3.12.3: Keywords for event specification

In the next step you can choose to select a certain point of time within the specified event. This closer selection is separated from the event specification with an underscore. If you don't select a certain point of time, "UK's Kalender" assumes you mean the start date and time.

Table 3.12.4: Keywords for closer specification of the selected part of the event

After you have determined the date or date range you can select which part of this date or date range you want to display. This specification is separated from the previous part by an underscore again.

Table 3.12.5: Keywords for the date specification

If you don't want to display date information but just how often an event already occured, you can use the keyword "COUNT" instead of a date specification. This will only make sense for repetitive events and works only if the previous keyword is not "STARTTOEND".

3.12.2.1 Display of time ranges

If you want to calculate a time range, you can replace the date specification by the keyword "TO". This will only work if the previous keyword is not "STARTTOEND". By the keyword "TO" you tell "UK's Kalender" not to output a date but to calculate a time difference. For calculating a difference you need to specify a second date. This second date is separated from the preceding "TO" by an underscore and follows the same specification rules as the first date.

With a date specifier or the keyword "TO" and a second date, the variable definition is complete. If you have calculated a time range still there is no output yet. Instead, the time difference is calculated and stored in the system variable "SPAN". This system variable can be formatted and displayed. For this, append an underscore and a time unit to the keyword "SPAN". Following time units are available:

Tables 3.12.6: Units for time range formatting

After retrieving a time range by calling "SPAN", e.g. with "$SPAN_YEARS$", the system variable "SPAN" is automatically decreased by the amount of time already displayed. This way it is possible to display the remainder of the time difference, e.g. by calling "$SPAN_DAYS$".

3.12.2.2 Extended formatting of positive and negative time differences

Without special formatting, calculated time differences are displayed without sign, if they are positive (the second date lies behind the first date, e.g. $THIS_TO_NEXT$ or $THIS_START_TO_THIS_END$) and with a negative sign if they are negative (the second date lies before the first date, e.g. $THIS_TO_FIRST$ or $THIS_END_TO_THIS_START$). You can change this if you specify different prefixes. For this you need to put the prefix for a positive difference followed by an underscore and the negative prefix just after the "$SPAN_" part. You might also specify a postfix. Simply put the postfix for positive differences, an underscore and the postfix for negative differences right before the closing "$".

This allows displaying correct sentences. The term:
$NOW_TO_THIS$Submission deadline $SPAN_is in _was _DAYS_ days_ days ago$
generates the display "Submission deadline is in 3 days" if at the time of calling there are three days left to the beginning of the event. Five days after the start date of the event, the output will be "Submission deadline was 5 days ago".

3.12.2.3 Conditional spaces and line breaks

All event variables can be preceded or succeeded by a conditional space or line break.The condition for inserting a space or line break is, that the variable itself is not empty. This makes sense with variables like "$NOTES" as they are not always filled out. If this variable holds some text it is probably good to show it in a separate line. On the other hand, if it is empty there is no need for an additional empty line.

The syntax is easy: You can put a "R" for a line break and/or a "S" for a space just after the leading "$" and/or right before the trailing "$". Like always, these symbols are separated from the keyword by underscores. The "$NOTES$" problem described above can be solved with the term "$R_NOTES$".

3.12.2.4 Temporarily switching the date format

All dates are using a standard format which can be defined under "Extras/Internal Formats..." from the menu (see chapter 3.13 for more information). If you want to use a different date format for a certain display, you can temporarily switch the date format by setting the following system variables:

Table 3.12.7: System variables for the date and time format

You can set a new format by putting the new format right after the name of the system variable. This time no underscore is required. For e.g. setting the time format to 24-hour format for one single call, you can do this by calling: $TIMEFORMAT%H:%M$

The formatting is only valid for this one call or until the next formatting statement.

3.12.3 ToDo formats

Todos can be formatted similar as events, so only the differences should be described here.

Just like with events, simple variables are available for accessing basic todo information:

Table 3.12.8: Simple todo variables

As there are no repetitive todos the are only a few date specifier:

Table 3.12.9: Keywords for the date specification of a todo entry

Todos don't have a duration, so the keywords "START", "END" and "STARTTOEND" do not exist.

All other mechanisms, including date range calculation, formatting positive or negative time differences, date and time formatting and conditional spaces and line breaks work just like with events.

3.12.4 Examples

Here you'll find some examples you can directly use in "UK's Kalender".

3.12.4.1 Age display for birthday reminders

For birthday events it's best to create a separate category by choosing "Extras / Categories..." from the menu and filling the template with the following settings:

• Category: Birthday
• Description: $FIRST_TO_THIS$$SPAN_YEARS$. Birthday
• Forewarn: 3 days (or whatever you find appropriate)
• Repetition: Yearly

To enter a new birthday, simply select the category "Birthday", enter the name of the person before the already existing description and select the actual date of birth (including the year!) as start date. "UK's Kalender" will show up the correct age of the person, e.g. "Peters 39. Birthday".

3.12.4.2 Showing the remaining time until the deadline of a todo

Enter the following term as the description of the todo:

$NOW_TO_DEADLINE$Deadline $SPAN_is in _was _DAYS_ days_ days ago$

Until the deadline the display will be "Deadline is in n days". After the deadline it will change to "Deadline was n days ago", "n" is the amount of days. Please note, that the display will not be updated while "UK's Kalender" is running. The display will only change after restarting the program or changing the state of the todo (done or undone).

3.12.4.3 Showing the remaining days until the next occurrence of an event

This function is useful, if the distance between two occurrences of a repetitive event varies, e.g. if you want to be reminded of every Friday the 13th.

Enter the following description for the event:

Next occurrence is in $THIS_TO_NEXT$$SPAN_DAYS$ days

You can extend this term with the actual date of the next occurrence:

The next occurrence is on $NEXT_AUTO$, there are $THIS_TO_NEXT$$SPAN_DAYS$ days left

3.12.4.4 Showing the remaining days until the end of a multi day event

You can use this e.g. for showing the remaining holidays:

$THISSELECTED_TO_THIS_END$$SPAN_DAYS$ days left