TikZ and PGF Manual

\usetikzlibrary{calendar} % LaTeX and plain TeX
\usetikzlibrary[calendar] % ConTeXt

The library defines the \calendar command, which can be used to typeset calendars. The command relies on the \pgfcalendar command from the pgfcalendar package, which is loaded automatically.

The \calendar command is quite configurable, allowing you to produce all kinds of different calendars.

The syntax for this command is similar to commands like \node or \matrix. However, it has its complete own parser and only those commands described in the following will be recognized, nothing else. Note, furthermore, that a ⟨calendar specification⟩ is not a path specification, indeed, no path is created for the calendar.

The specification syntax. The ⟨calendar specification⟩ must be a sequence of elements, each of which has one of the following structures:

• • [⟨options⟩]

  You provide ⟨options⟩ in square brackets as in [red,draw=none]. These ⟨options⟩ can be any TikZ option and they apply to the whole calendar. You can provide this element multiple times, the effect accumulates.

• • (⟨name⟩)

  This has the same effect as saying [name=⟨name⟩]. The effect of providing a ⟨name⟩ is explained later. Note already that a calendar is not a node and the ⟨name⟩ is not the name of a node.

• • at (⟨coordinate⟩)

  This has the same effect as saying [at=(⟨coordinate⟩)].

• • if (⟨date condition⟩) ⟨options or commands⟩else⟨else options or commands⟩

  The effect of such an if is explained later.

At the beginning of every calendar, the following style is used:

The date range. The overall effect of the \calendar command is to execute code for each day of a range of dates. This range of dates is set using the following option:

It will be useful to fix two pieces of terminology for the following descriptions: The \calendar command iterates over the dates in the range. The current date refers to the current date the command is processing as it iterates over the dates. For each current date code is executed, which will be called the current date code. The current date code consists of different parts, to be detailed later.

The central part of the current date code is the execution of the code \tikzdaycode. By default, this code simply produces a node whose text is set to the day of month. This means that unless further action is taken, all days of a calendar will be put on top of each other! To avoid this, you must modify the current date code to shift days around appropriately. Predefined arrangements like day list downward or week list do this for you, but you can define arrangements yourself. Since defining an arrangement is a bit tricky, it is explained only later on. For the time being, let us use a predefined arrangement to produce our first calendar:

Changing the spacing. In the above calendar, the spacing between the days is determined by numerous options. Most arrangements do not use all of these options, but only those that apply naturally.

Changing the position of the calendar. The calendar is placed in such a way that, normally, the anchor of the first day label is at the origin. This can be changed by using the at option. When you say at={(1,1)}, this anchor of the first day will lie at coordinate \((1,1)\).

In general, arrangements will not always place the anchor of the first day at the origin. Sometimes, additional spacing rules get in the way. There are different ways of addressing this problem: First, you can just ignore it. Since calendars are often placed in their own {tikzpicture} and since their size is computed automatically, the exact position of the origin often does not matter at all. Second, you can put the calendar inside a node as in ...node {\tikz \calendar...}. This allows you to position the node in the normal ways using the node’s anchors. Third, you can be very clever and use a single-cell matrix. The advantage is that a matrix allows you to provide any anchor of any node inside the matrix as an anchor for the whole matrix. For example, the following calendar is placed in such a way the center of 2000-01-20 lies on the position \((2,2)\):

Unfortunately, the matrix-base positions, which is the cleanest way, isn’t as portable as the other approaches (it currently does not work with the svg backend for instance).

Changing the appearance of days. As mentioned before, each day in the above calendar is produced by an execution of the \tikzdaycode. Each time this code is executed, the coordinate system will have been set up appropriately to place the day of the month correctly. You can change both the code and its appearance using the following options.

Changing the appearance of month and year labels. In addition to the days of a calendar, labels for the months and even years (for really long calendars) can be added. These labels are only added once per month or year and this is not done by default. Rather, special styles starting with month label place these labels and make them visible:

The following options change the appearance of the month and year label:

Date ifs. Much of the power of the \calendar command comes from the use of conditionals. There are two equivalent way of specifying such a conditional. First, you can add the text if (⟨conditions⟩) ⟨code or options⟩ to your ⟨calendar specification⟩, possibly followed by else⟨else code or options⟩. You can have multiple such conditionals (but you cannot nest them in this simple manner). The second way is to use the following option:

Now, regardless of how you specify a conditional, it has the following effect (individually and independently for each date in the calendar):

• 1. It is checked whether the current date is one of the possibilities listed in ⟨conditions⟩. An example of such a condition is Sunday. Thus, when you write if (Saturday,Sunday) {foo}, then foo will be executed for every day in the calendar that is a Saturday or a Sunday.

  The command \ifdate and, thereby, \pgfcalendarifdate are used to evaluate the ⟨conditions⟩, see section 89.1.2 for a complete list of possible tests. The most useful tests are: Tests like Monday and so on, workday for the days Monday to Friday, weekend for Saturday and Sunday, equals for testing whether the current date equals a given date, at least and at least for comparing the current date with a given date.

• 2. If the date passes the check, the ⟨code or options⟩ is evaluated in a manner to be described in a moment; if the date fails, the ⟨else code or options⟩ is evaluated, if present.

  The ⟨code or options⟩ can either be some code. This is indicated by surrounding the code with curly braces. It can also be a list of TikZ options. This is indicated by surrounding the options with square brackets. For example in the date test if (Sunday) {\draw...} else {\fill...} there are two pieces of code involved. By comparison, if (Sunday) [red] else [green] involves two options.

  If ⟨code or options⟩ is code, it is simply executed (for the current day). If it is a list of options, these options are passed to a scope surrounding the current date.

Let us now have a look at some examples. First, we use a conditional to make all Sundays red.

Next, let us do something on a specific date:

You might wonder why the circle seems to be “off” the date. Actually, it is centered on the date, it is just that the date label uses the base east anchor, which shifts the label up and right. To overcome this problem we can change the anchor:

However, the single day dates are now no longer aligned correctly. For this, we can change the day text to \%d=, which adds a space at the beginning of single day text.

In the following, more technical information is covered. Most readers may wish to skip it.

The current date code. As mentioned earlier, for each date in the calendar the current date code is executed. It is the job of this code to shift around date nodes, to render the date nodes, to draw the month labels and to do all other stuff that is necessary to draw a calendar.

The current date code consists of the following parts, in this order:

• 1. The before-scope code.

• 2. A scope is opened.

• 3. The at-begin-scope code.

• 4. All date-ifs from the ⟨calendar specification⟩ are executed.

• 5. The at-end-scope code.

• 6. The scope is closed.

• 7. The after-scope code.

All of the codes mentioned above can be changed using appropriate options, see below. In case you wonder why so many are needed, the reason is that the current date code as a whole is not surrounded by a scope or TeX group. This means that code executed in the before-scope code and in the after-scope code has an effect on all following days. For example, if the after-scope code modifies the transformation matrix by shifting everything downward, all following days will be shifted downward. If each day does this, you get a list of days, one below the other.

However, you do not always want code to have an effect on everything that follows. For instance, if a day has the date-if if (Sunday) [red], we only want this Sunday to red, not all following days also. Similarly, sometimes it is easier to compute the position of a day relative to a fixed origin and we do not want any modifications of the transformation matrix to have an effect outside the scope.

By cleverly adjusting the different codes, all sorts of different day arrangements are possible.

This style causes the days of a month to be typeset one below the other. The shift between days is given by day yshift. Between month an additional shift of month yshift is added.

Works as above, only the list grows upward instead of downward.

This style also works as before, but the list of days grows to the right. Instead of day yshift and month yshift, the values of day xshift and month xshift are used.

As above, but the list grows left.

This style creates one row for each week in the range. The value of day xshift is used for the distance between days in each week row, the value of day yshift is used for the distance between rows. In both cases, “distance” refers to the distance between the anchors of the nodes of the days (or, more generally, the distance between the origins of the little pictures created for each day).

The days inside each week are shifted such that Monday is always at the first position (to change this, you need to copy and then modify the code appropriately). If the date range does not start on a Monday, the first line will not start in the first column, but rather in the column appropriate for the first date in the range.

At the beginning of each month (except for the first month in the range) an additional vertical space of month yshift is added. If this is set to 0pt you get a continuous list of days.

In this arrangement there is a row for each month. As for the week list, the day xshift is used for the horizontal distance. For the vertical shift, month yshift is used.

In each row, all days of the month are listed alongside each other. However, it is once more ensured that days in each column lie on the same day of week. Thus, the very first column contains only Mondays. If a month does not start with a Monday, its days are shifted to the right such that the days lie on the correct columns.

Places the month label to the left of the first day of the month. (For week list and month list where a month does not start on a Monday, the position is chosen “as if” the month had started on a Monday – which is usually exactly what you want.)

This style works like the above style, only the label is rotated counterclockwise by 90 degrees.

This style places the month label to the right of the row in which the first day of the month lies. This means that for a day list the label is to the right of the first day, for a week list it is to the right of the first week, and for a month list it is to the right of the whole month.

Works as above, only the label is rotated clockwise by 90 degrees.

This style places the month label above of the row of the first day, flushed left to the leftmost column. The amount by which the label is raised is fixed to 1.25em; use the yshift option with the month node to modify this.

Works as above, only the label is centered above the row containing the first day.

Works as above, but flushed right

Works like month label above left, only the label is placed below the row. This placement is not really useful with the week list arrangement, but rather with the day list right or month list arrangement.

Works like month label above centered, only below.