Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-calendar.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Calendar Library}
12 \label{section-calender}
13
14 \begin{tikzlibrary}{calendar}
15 The library defines the |\calendar| command, which can be used to typeset
16 calendars. The command relies on the |\pgfcalendar| command from the
17 |pgfcalendar| package, which is loaded automatically.
18
19 The |\calendar| command is quite configurable, allowing you to produce all
20 kinds of different calendars.
21 \end{tikzlibrary}
22
23
24 \subsection{Calendar Command}
25
26 The core command for creating calendars in \tikzname\ is the |\calendar|
27 command. It is available only inside |{tikzpicture}| environments (similar to,
28 say, the |\draw| command).
29
30 \begin{command}{\calendar \meta{calendar specification}|;|}
31 The syntax for this command is similar to commands like |\node| or
32 |\matrix|. However, it has its complete own parser and only those commands
33 described in the following will be recognized, nothing else. Note,
34 furthermore, that a \meta{calendar specification} is not a path
35 specification, indeed, no path is created for the calendar.
36
37
38 \medskip
39 \textbf{The specification syntax.}
40 The \meta{calendar specification} must be a sequence of elements, each of
41 which has one of the following structures:
42 %
43 \begin{itemize}
44 \item |[|\meta{options}|]|
45
46 You provide \meta{options} in square brackets as in
47 |[red,draw=none]|. These \meta{options} can be any \tikzname\
48 option and they apply to the whole calendar. You can provide this
49 element multiple times, the effect accumulates.
50 \item |(|\meta{name}|)|
51
52 This has the same effect as saying |[name=|\meta{name}|]|. The
53 effect of providing a \meta{name} is explained later. Note already
54 that \emph{a calendar is not a node} and the \meta{name} is
55 \emph{not the name of a node}.
56 \item |at (|\meta{coordinate}|)|
57
58 This has the same effect as saying |[at=(|\meta{coordinate}|)]|.
59 \item |if (|\meta{date condition}|)| \meta{options or commands}\opt{|else|\meta{else options or commands}}
60
61 The effect of such an |if| is explained later.
62 \end{itemize}
63
64 At the beginning of every calendar, the following style is used:
65 %
66 \begin{stylekey}{/tikz/every calendar (initially \normalfont empty)}
67 This style is used with every calendar.
68 \end{stylekey}
69
70
71 \medskip
72 \textbf{The date range.}
73 The overall effect of the |\calendar| command is to execute code for each
74 day of a range of dates. This range of dates is set using the following
75 option:
76 %
77 \begin{key}{/tikz/dates=\meta{start date}| to |\meta{end date}}
78 This option specifies the date range. Both the start and end date are
79 specified and described on page~\pageref{calendar-date-format}. In
80 short: You can provide ISO-format type dates like |2006-01-02|, you can
81 replace the day of month by |last| to refer to the last day of a month
82 (so |2006-02-last| is the same as |2006-02-28|), and you can add a plus
83 sign followed by a number to specify an offset (so |2006-01-01+-1| is
84 the same as |2005-12-31|).
85 \end{key}
86 %
87 It will be useful to fix two pieces of terminology for the following
88 descriptions: The |\calendar| command iterates over the dates in the range.
89 The \emph{current date} refers to the current date the command is
90 processing as it iterates over the dates. For each current date code is
91 executed, which will be called the \emph{current date code}. The current
92 date code consists of different parts, to be detailed later.
93
94 The central part of the current date code is the execution of the code
95 |\tikzdaycode|. By default, this code simply produces a node whose text is
96 set to the day of month. This means that unless further action is taken,
97 all days of a calendar will be put on top of each other! To avoid this, you
98 must modify the current date code to shift days around appropriately.
99 Predefined arrangements like |day list downward| or |week list| do this for
100 you, but you can define arrangements yourself. Since defining an
101 arrangement is a bit tricky, it is explained only later on. For the time
102 being, let us use a predefined arrangement to produce our first calendar:
103 %
104 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
105 \tikz \calendar[dates=2000-01-01 to 2000-01-31,week list];
106 \end{codeexample}
107
108
109 \medskip
110 \textbf{Changing the spacing.}
111 In the above calendar, the spacing between the days is determined by
112 numerous options. Most arrangements do not use all of these options, but
113 only those that apply naturally.
114 %
115 \begin{key}{/tikz/day xshift=\meta{dimension} (initially 3.5ex)}
116 Specifies the horizontal shift between days. This is not the gap
117 between days, but the shift between the anchors of their nodes.
118 %
119 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
120 \tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,day xshift=3ex];
121 \end{codeexample}
122 \end{key}
123 %
124 \begin{key}{/tikz/day yshift=\meta{dimension} (initially 3ex)}
125 Specifies the vertical shift between days. Again, this is the shift
126 between the anchors of their nodes.
127 %
128 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
129 \tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,day yshift=2ex];
130 \end{codeexample}
131 \end{key}
132 %
133 \begin{key}{/tikz/month xshift=\meta{dimension}}
134 Specifies an additional horizontal shift between different months.
135 \end{key}
136 %
137 \begin{key}{/tikz/month yshift=\meta{dimension}}
138 Specifies an additional vertical shift between different months.
139 %
140 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
141 \tikz \calendar[dates=2000-01-01 to 2000-02-last,week list,
142 month yshift=0pt];
143 \end{codeexample}
144 %
145 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
146 \tikz \calendar[dates=2000-01-01 to 2000-02-last,week list,
147 month yshift=1cm];
148 \end{codeexample}
149 \end{key}
150
151
152 \medskip
153 \textbf{Changing the position of the calendar.}
154 The calendar is placed in such a way that, normally, the anchor of the
155 first day label is at the origin. This can be changed by using the |at|
156 option. When you say |at={(1,1)}|, this anchor of the first day will lie at
157 coordinate $(1,1)$.
158
159 In general, arrangements will not always place the anchor of the first day
160 at the origin. Sometimes, additional spacing rules get in the way. There
161 are different ways of addressing this problem: First, you can just ignore
162 it. Since calendars are often placed in their own |{tikzpicture}| and since
163 their size is computed automatically, the exact position of the origin
164 often does not matter at all. Second, you can put the calendar inside a
165 node as in |...node {\tikz \calendar...}|. This allows you to position the
166 node in the normal ways using the node's anchors. Third, you can be very
167 clever and use a single-cell matrix. The advantage is that a matrix allows
168 you to provide any anchor of any node inside the matrix as an anchor for
169 the whole matrix. For example, the following calendar is placed in such a
170 way the center of 2000-01-20 lies on the position $(2,2)$:
171 %
172 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
173 \begin{tikzpicture}
174 \draw[help lines] (0,0) grid (3,2);
175 \matrix [anchor=cal-2000-01-20.center] at (2,2)
176 { \calendar(cal)[dates=2000-01-01 to 2000-01-31,week list]; \\};
177 \end{tikzpicture}
178 \end{codeexample}
179 %
180 Unfortunately, the matrix-base positions, which is the cleanest way, isn't
181 as portable as the other approaches (it currently does not work with the
182 \textsc{svg} backend for instance).
183
184
185 \medskip
186 \textbf{Changing the appearance of days.}
187 As mentioned before, each day in the above calendar is produced by an
188 execution of the |\tikzdaycode|. Each time this code is executed, the
189 coordinate system will have been set up appropriately to place the day of
190 the month correctly. You can change both the code and its appearance using
191 the following options.
192 %
193 \begin{key}{/tikz/day code=\meta{code} (initially \normalfont see below)}
194 This option allows you to change the code that is executed for each
195 day. The default is to create a node with an appropriate name, but you
196 can change this:
197 %
198 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
199 \tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
200 day code={\fill[blue] (0,0) circle (2pt);}];
201 \end{codeexample}
202 %
203 The default code is the following:
204 %
205 \begin{codeexample}[code only]
206 \node[name=\pgfcalendarsuggestedname,every day]{\tikzdaytext};
207 \end{codeexample}
208 %
209 The first part causes the day nodes to be accessible via the following
210 names: If \meta{name} is the name given to the calendar via a |name=|
211 option or via the specification element |(|\meta{name}|)|, then
212 |\pgfcalendarsuggestedname| will expand to \meta{name}|-|\meta{date},
213 where \meta{date} is the date of the day that is currently being
214 processed in ISO format.
215
216 For example, if January 1, 2006 is being processed and the calendar has
217 been named |mycal|, then the node containing the |1| for this date will
218 be names |mycal-2006-01-01|. You can later reference this node.
219 %
220 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
221 \begin{tikzpicture}
222 \calendar (mycal) [dates=2000-01-01 to 2000-01-31,week list];
223
224 \draw[red] (mycal-2000-01-20) circle (4pt);
225 \end{tikzpicture}
226 \end{codeexample}
227 \end{key}
228
229 \begin{key}{/tikz/day text=\meta{text}}
230 This option changes the setting of the |\tikzdaytext|. By default, this
231 macro simply yields the current day of month, but you can change it
232 arbitrarily. Here is a silly example:
233 %
234 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
235 \tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
236 day text=x];
237 \end{codeexample}
238 %
239 More useful examples are based on using the |\%| command. This command
240 is redefined inside a |\pgfcalendar| to mean the same as
241 |\pgfcalendarshorthand|. (The original meaning of |\%| is lost inside
242 the calendar, you need to save if before the calendar if you really
243 need it.)
244
245 The |\%| inserts the current day/month/year/day of week in a certain
246 format into the text. The first letter following the |\%| selects the
247 type (permissible values are |d|, |m|, |y|, |w|), the second letter
248 specifies how the value should be displayed (|-| means numerically, |=|
249 means numerically with leading space, |0| means numerically with
250 leading zeros, |t| means textual, and |.| means textual, abbreviated).
251 For example |\%d0| gives the day with a leading zero (for more details
252 see the description of |\pgfcalendarshorthand| on
253 page~\pageref{pgfcalendarshorthand}).
254
255 Let us redefine the |day text| so that it yields the day with a leading
256 zero:
257 %
258 \begin{codeexample}[leave comments,preamble={\usetikzlibrary{calendar}}]
259 \tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
260 day text=\%d0];
261 \end{codeexample}
262 \end{key}
263
264 \begin{key}{/tikz/every day (initially {anchor=base east})}
265 This style is executed by the default node code for each day. The
266 |every day| style is useful for changing the way days look. For
267 example, let us make all days red:
268 %
269 \begin{codeexample}[leave comments,preamble={\usetikzlibrary{calendar}}]
270 \tikz[every day/.style=red]
271 \calendar[dates=2000-01-01 to 2000-01-31,week list];
272 \end{codeexample}
273 \end{key}
274
275
276 \medskip
277 \textbf{Changing the appearance of month and year labels.}
278 In addition to the days of a calendar, labels for the months and even years
279 (for really long calendars) can be added. These labels are only added once
280 per month or year and this is not done by default. Rather, special styles
281 starting with |month label| place these labels and make them visible:
282 %
283 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
284 \tikz \calendar[dates=2000-01-01 to 2000-02-last,week list,
285 month label above centered];
286 \end{codeexample}
287
288 The following options change the appearance of the month and year label:
289 %
290 \begin{key}{/tikz/month code=\meta{code} (initially \normalfont see below)}
291 This option allows you to specify what the macro |\tikzmonthcode|
292 should expand to.
293
294 By default, the |\tikzmonthcode| it is set to
295 %
296 \begin{codeexample}[code only]
297 \node[every month]{\tikzmonthtext};
298 \end{codeexample}
299 %
300 Note that this node is not named by default.
301 \end{key}
302
303 \begin{key}{/tikz/month text=\meta{text}}
304 This option allows you to change the macro |\tikzmonthtext|. By
305 default, the month text is a long textual presentation of the current
306 month being typeset.
307 %
308 \begin{codeexample}[leave comments,preamble={\usetikzlibrary{calendar}}]
309 \tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
310 month label above centered,
311 month text=\textcolor{red}{\%mt} \%y-];
312 \end{codeexample}
313 \end{key}
314
315 \begin{stylekey}{/tikz/every month (initially \normalfont empty)}
316 This style can be used to change the appearance of month labels.
317 \end{stylekey}
318
319 \begin{key}{/tikz/year code=\meta{code}}
320 Works like |month code|, only for years.
321 \end{key}
322
323 \begin{key}{/tikz/year text=\meta{text}}
324 Works like |month text|, only for years.
325 \end{key}
326
327
328 \begin{key}{/tikz/every year}
329 Works like |every month|, only for years.
330 \end{key}
331
332
333 \medskip
334 \textbf{Date ifs.}
335 Much of the power of the |\calendar| command comes from the use of
336 conditionals. There are two equivalent way of specifying such a
337 conditional. First, you can add the text
338 |if (|\meta{conditions}|) |\meta{code or options} to your \meta{calendar
339 specification}, possibly followed by |else|\meta{else code or options}. You
340 can have multiple such conditionals (but you cannot nest them in this
341 simple manner). The second way is to use the following option:
342 %
343 \begin{key}{/tikz/if=|(|\meta{conditions}|)|\meta{code or options}\opt{|else|\meta{else code or options}}}
344 This option has the same effect as giving a corresponding if in the
345 \meta{calendar specification}. The option is mostly useful for use in
346 the |every calendar| style, where you cannot provide if conditionals
347 otherwise.
348 \end{key}
349 %
350 Now, regardless of how you specify a conditional, it has the following
351 effect (individually and independently for each date in the calendar):
352 %
353 \begin{enumerate}
354 \item It is checked whether the current date is one of the
355 possibilities listed in \meta{conditions}. An example of such a
356 condition is |Sunday|. Thus, when you write
357 |if (Saturday,Sunday) {foo}|, then |foo| will be executed for every
358 day in the calendar that is a Saturday \emph{or} a Sunday.
359
360 The command |\ifdate| and, thereby, |\pgfcalendarifdate| are used
361 to evaluate the \meta{conditions}, see
362 page~\pageref{pgfcalendarifdate} for a complete list of possible
363 tests. The most useful tests are: Tests like |Monday| and so on,
364 |workday| for the days Monday to Friday, |weekend| for Saturday and
365 Sunday, |equals| for testing whether the current date equals a
366 given date, |at least| and |at least| for comparing the current
367 date with a given date.
368 \item If the date passes the check, the \meta{code or options} is
369 evaluated in a manner to be described in a moment; if the date
370 fails, the \meta{else code or options} is evaluated, if present.
371
372 The \meta{code or options} can either be some code. This is
373 indicated by surrounding the code with curly braces. It can also be
374 a list of \tikzname\ options. This is indicated by surrounding the
375 options with square brackets. For example in the date test
376 |if (Sunday) {\draw...} else {\fill...}| there are two pieces of
377 code involved. By comparison, |if (Sunday) [red] else [green]|
378 involves two options.
379
380 If \meta{code or options} is code, it is simply executed (for the
381 current day). If it is a list of options, these options are passed
382 to a scope surrounding the current date.
383 \end{enumerate}
384 %
385 Let us now have a look at some examples. First, we use a conditional to
386 make all Sundays red.
387 %
388 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
389 \tikz
390 \calendar
391 [dates=2000-01-01 to 2000-01-31,week list]
392 if (Sunday) [red];
393 \end{codeexample}
394 %
395 Next, let us do something on a specific date:
396 %
397 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
398 \tikz
399 \calendar
400 [dates=2000-01-01 to 2000-01-31,week list]
401 if (Sunday) [red]
402 if (equals=2000-01-20) {\draw (0,0) circle (8pt);};
403 \end{codeexample}
404 %
405 You might wonder why the circle seems to be ``off'' the date. Actually, it
406 is centered on the date, it is just that the date label uses the
407 |base east| anchor, which shifts the label up and right. To overcome this
408 problem we can change the anchor:
409 %
410 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
411 \tikz [every day/.style={anchor=mid}]
412 \calendar
413 [dates=2000-01-01 to 2000-01-31,week list]
414 if (Sunday) [red]
415 if (equals=2000-01-20) {\draw (0,0) circle (8pt);};
416 \end{codeexample}
417 %
418 However, the single day dates are now no longer aligned correctly. For
419 this, we can change the day text to |\%d=|, which adds a space at the
420 beginning of single day text.
421
422 In the following, more technical information is covered. Most readers may
423 wish to skip it.
424
425 \medskip
426 \textbf{The current date code.}
427 As mentioned earlier, for each date in the calendar the current date code
428 is executed. It is the job of this code to shift around date nodes, to
429 render the date nodes, to draw the month labels and to do all other stuff
430 that is necessary to draw a calendar.
431
432 The current date code consists of the following parts, in this order:
433 %
434 \begin{enumerate}
435 \item The before-scope code.
436 \item A scope is opened.
437 \item The at-begin-scope code.
438 \item All date-ifs from the \meta{calendar specification} are executed.
439 \item The at-end-scope code.
440 \item The scope is closed.
441 \item The after-scope code.
442 \end{enumerate}
443 %
444 All of the codes mentioned above can be changed using appropriate options,
445 see below. In case you wonder why so many are needed, the reason is that
446 the current date code as a whole is not surrounded by a scope or \TeX\
447 group. This means that code executed in the before-scope code and in the
448 after-scope code has an effect on all following days. For example, if the
449 after-scope code modifies the transformation matrix by shifting everything
450 downward, all following days will be shifted downward. If each day does
451 this, you get a list of days, one below the other.
452
453 However, you do not always want code to have an effect on everything that
454 follows. For instance, if a day has the date-if |if (Sunday) [red]|, we
455 only want this Sunday to red, not all following days also. Similarly,
456 sometimes it is easier to compute the position of a day relative to a fixed
457 origin and we do not want any modifications of the transformation matrix to
458 have an effect outside the scope.
459
460 By cleverly adjusting the different codes, all sorts of different day
461 arrangements are possible.
462
463 \begin{key}{/tikz/execute before day scope=\meta{code}}
464 The \meta{code} is executed before everything else for each date.
465 Multiple calls of this option have an accumulative effect. Thus, if you
466 use this option twice, the code from the first use is used first for
467 each day, followed by the code given the second time.
468 \end{key}
469 %
470 \begin{key}{/tikz/execute at begin day scope=\meta{code}}
471 This code is execute before everything else inside the scope of the
472 current date. Again, the effect is accumulative.
473 \end{key}
474 %
475 \begin{key}{/tikz/execute at end day scope=\meta{code}}
476 This code is executed just before the day scope is closed. The effect
477 is also accumulative, however, in reverse order. This is useful to
478 pair, say, |\scope| and |\endscope| commands in at-begin- and
479 at-end-code.
480 \end{key}
481 %
482 \begin{key}{/tikz/execute after day scope=\meta{code}}
483 This is executed at the very end of the current date, outside the
484 scope. The accumulation is also in reverse.
485 \end{key}
486 \end{command}
487
488 In the rest of the following subsections we have a look at how the different
489 scope codes can be used to create different calendar arrangements.
490
491
492 \subsubsection{Creating a Simple List of Days}
493
494 We start with a list of the days of the calendar, one day below the other. For
495 this, we simply shift the coordinate system downward at the end of the code for
496 each day. This shift must be \emph{outside} the day scope as we want day shifts
497 to accumulate. Thus, we use the following code:
498 %
499 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
500 \tikz
501 \calendar [dates=2000-01-01 to 2000-01-08,
502 execute after day scope=
503 {\pgftransformyshift{-1em}}];
504 \end{codeexample}
505 %
506 Clearly, we can use this approach to create day lists going up, down, right,
507 left, or even diagonally.
508
509
510 \subsubsection{Adding a Month Label}
511
512 We now want to add a month label to the left of the beginning of each month.
513 The idea is to do two things:
514 %
515 \begin{enumerate}
516 \item We add code that is executed only on the first of each month.
517 \item The code is executed before the actual day is rendered. This ensures
518 that options applying to the days do not affect the month rendering.
519 \end{enumerate}
520 %
521 We have two options where we should add the month code: Either we add it at the
522 beginning of the day scope or before. Either will work fine, but it might be
523 safer to put the code inside the scope to ensure that settings to not
524 inadvertently ``leak outside''.
525 %
526 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
527 \tikz
528 \calendar
529 [dates=2000-01-01 to 2000-01-08,
530 execute after day scope={\pgftransformyshift{-1em}},
531 execute at begin day scope=
532 {\ifdate{day of month=1}{\tikzmonthcode}{}},
533 every month/.append style={anchor=base east,xshift=-2em}];
534 \end{codeexample}
535
536 In the above code we used the |\ifdate|\marg{condition}\marg{then
537 code}\marg{else code} command, which is described on page~\pageref{ifdate} in
538 detail and which has much the same effect as
539 |if (|\meta{condition}|)|\marg{then code}| else |\marg{else code}, but works in
540 normal code.
541
542
543 \subsubsection{Creating a Week List Arrangement}
544
545 Let us now address a more complicated arrangement: A week list. In this
546 arrangement there is line for each week. The horizontal placement of the days
547 is thus that all Mondays lie below each other, likewise for all Tuesdays, and
548 so on.
549
550 In order to typeset this arrangement, we can use the following approach: The
551 origin of the coordinate system rests at the anchor for the Monday of each
552 week. That means that at the end of each week the origin is moved downward one
553 line. On all other days, the origin at the end of the day code is the same as
554 at the beginning. To position each day correctly, we use code inside and at the
555 beginning of the day scope to horizontally shift the day according to its day
556 of week.
557 %
558 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
559 \tikz
560 \calendar
561 [dates=2000-01-01 to 2000-01-20,
562 % each day is shifted right according to the day of week
563 execute at begin day scope=
564 {\pgftransformxshift{\pgfcalendarcurrentweekday em}},
565 % after each week, the origin is shifted downward:
566 execute after day scope=
567 {\ifdate{Sunday}{\pgftransformyshift{-1em}}{}}];
568 \end{codeexample}
569
570
571 \subsubsection{Creating a Month List Arrangement}
572
573 For another example, let us create an arrangement that contains one line for
574 each month. This is easy enough to do as for weeks, unless we add the following
575 requirement: Again, we want all days in a column to have the same day of week.
576 Since months start on different days of week, this means that each row has to
577 have an individual offset.
578
579 One possible way is to use the following approach: After each month (or at the
580 beginning of each month) we advance the vertical position of the offset by one
581 line. For horizontal placement, inside the day scope we locally shift the day
582 by its day of month. Furthermore, we must additionally shift the day to ensure
583 that the first day of the month lies on the correct day of week column. For
584 this, we remember this day of week the first time we see it.
585 %
586 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
587 \newcount\mycount
588 \tikz
589 \calendar
590 [dates=2000-01-01 to 2000-02-last,
591 execute before day scope=
592 {
593 \ifdate{day of month=1} {
594 % Remember the weekday of first day of month
595 \mycount=\pgfcalendarcurrentweekday
596 % Shift downward
597 \pgftransformyshift{-1em}
598 }{}
599 },
600 execute at begin day scope=
601 {
602 % each day is shifted right according to the day of month
603 \pgftransformxshift{\pgfcalendarcurrentday em}
604 % and additionally according to the weekday of the first
605 \pgftransformxshift{\the\mycount em}
606 }];
607 \end{codeexample}
608
609
610 \subsection{Arrangements}
611
612 An \emph{arrangement} specifies how the days of calendar are arranged on the
613 page. The |calendar| library defines a number of predefined arrangements.
614
615 We start with arrangements in which the days are listed in a long line.
616
617 \begin{stylekey}{/tikz/day list downward}
618 This style causes the days of a month to be typeset one below the other.
619 The shift between days is given by |day yshift|. Between month an
620 additional shift of |month yshift| is added.
621 %
622 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
623 \tikz
624 \calendar [dates=2000-01-28 to 2000-02-03,
625 day list downward,month yshift=1em];
626 \end{codeexample}
627 %
628 \end{stylekey}
629
630 \begin{stylekey}{/tikz/day list upward}
631 Works as above, only the list grows upward instead of downward.
632 %
633 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
634 \tikz
635 \calendar [dates=2000-01-28 to 2000-02-03,
636 day list upward,month yshift=1em];
637 \end{codeexample}
638 %
639 \end{stylekey}
640
641 \begin{stylekey}{/tikz/day list right}
642 This style also works as before, but the list of days grows to the right.
643 Instead of |day yshift| and |month yshift|, the values of |day xshift| and
644 |month xshift| are used.
645 %
646 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
647 \tikz
648 \calendar [dates=2000-01-28 to 2000-02-03,
649 day list right,month xshift=1em];
650 \end{codeexample}
651 %
652 \end{stylekey}
653
654 \begin{stylekey}{/tikz/day list left}
655 As above, but the list grows left.
656 \end{stylekey}
657
658 The next arrangement lists days by the week.
659
660 \begin{stylekey}{/tikz/week list}
661 This style creates one row for each week in the range. The value of
662 |day xshift| is used for the distance between days in each week row, the
663 value of |day yshift| is used for the distance between rows. In both cases,
664 ``distance'' refers to the distance between the anchors of the nodes of the
665 days (or, more generally, the distance between the origins of the little
666 pictures created for each day).
667
668 The days inside each week are shifted such that Monday is always at the
669 first position (to change this, you need to copy and then modify the code
670 appropriately). If the date range does not start on a Monday, the first
671 line will not start in the first column, but rather in the column
672 appropriate for the first date in the range.
673
674 At the beginning of each month (except for the first month in the range) an
675 additional vertical space of |month yshift| is added. If this is set to
676 |0pt| you get a continuous list of days.
677 %
678 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
679 \tikz
680 \calendar [dates=2000-01-01 to 2000-02-last,week list];
681 \end{codeexample}
682 %
683 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
684 \tikz
685 \calendar [dates=2000-01-01 to 2000-02-last,week list,
686 month yshift=0pt];
687 \end{codeexample}
688 %
689 \end{stylekey}
690
691 The following arrangement gives a very compact view of a whole year.
692 %
693 \begin{stylekey}{/tikz/month list}
694 In this arrangement there is a row for each month. As for the |week list|,
695 the |day xshift| is used for the horizontal distance. For the vertical
696 shift, |month yshift| is used.
697
698 In each row, all days of the month are listed alongside each other.
699 However, it is once more ensured that days in each column lie on the same
700 day of week. Thus, the very first column contains only Mondays. If a month
701 does not start with a Monday, its days are shifted to the right such that
702 the days lie on the correct columns.
703 %
704 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
705 \sffamily\scriptsize
706 \tikz
707 \calendar [dates=2000-01-01 to 2000-12-31,
708 month list,month label left,month yshift=1.25em]
709 if (Sunday) [black!50];
710 \end{codeexample}
711 %
712 \end{stylekey}
713
714
715 \subsection{Month Labels}
716
717 For many calendars you may wish to add a label to each month. We have already
718 covered how month nodes are created and rendered in the description of the
719 |\calendar| command: use |month text|, |every month|, and also |month code| (if
720 necessary) to change the appearance of the month labels.
721
722 What we have not yet covered is where these labels are placed. By default, they
723 are not placed at all as there is no good ``default position'' for them.
724 Instead, you can use one of the following options to specify a position for the
725 labels:
726 %
727 \begin{stylekey}{/tikz/month label left}
728 Places the month label to the left of the first day of the month. (For
729 |week list| and |month list| where a month does not start on a Monday, the
730 position is chosen ``as if'' the month had started on a Monday -- which is
731 usually exactly what you want.)
732 %
733 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
734 \tikz
735 \calendar [dates=2000-01-28 to 2000-02-03,
736 day list downward,month yshift=1em,
737 month label left];
738 \end{codeexample}
739 %
740 \end{stylekey}
741
742 \begin{stylekey}{/tikz/month label left vertical}
743 This style works like the above style, only the label is rotated
744 counterclockwise by 90 degrees.
745 %
746 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
747 \tikz
748 \calendar [dates=2000-01-28 to 2000-02-03,
749 day list downward,month yshift=1em,
750 month label left vertical];
751 \end{codeexample}
752 %
753 \end{stylekey}
754
755 \begin{stylekey}{/tikz/month label right}
756 This style places the month label to the right of the row in which the
757 first day of the month lies. This means that for a day list the label is to
758 the right of the first day, for a week list it is to the right of the first
759 week, and for a month list it is to the right of the whole month.
760 %
761 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
762 \tikz
763 \calendar [dates=2000-01-28 to 2000-02-03,
764 day list downward,month yshift=1em,
765 month label right];
766 \end{codeexample}
767 %
768 \end{stylekey}
769
770 \begin{stylekey}{/tikz/month label right vertical}
771 Works as above, only the label is rotated clockwise by 90 degrees.
772 %
773 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
774 \tikz
775 \calendar [dates=2000-01-28 to 2000-02-03,
776 day list downward,month yshift=1em,
777 month label right vertical];
778 \end{codeexample}
779 %
780 \end{stylekey}
781
782 \begin{stylekey}{/tikz/month label above left}
783 This style places the month label above of the row of the first day,
784 flushed left to the leftmost column. The amount by which the label is
785 raised is fixed to |1.25em|; use the |yshift| option with the month node to
786 modify this.
787 %
788 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
789 \tikz
790 \calendar [dates=2000-01-28 to 2000-02-03,
791 day list right,month xshift=1em,
792 month label above left];
793 \end{codeexample}
794 %
795 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
796 \tikz
797 \calendar [dates=2000-01-20 to 2000-02-10,
798 week list,month label above left];
799 \end{codeexample}
800 %
801 \end{stylekey}
802
803 \begin{stylekey}{/tikz/month label above centered}
804 Works as above, only the label is centered above the row containing the
805 first day.
806 %
807 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
808 \tikz
809 \calendar [dates=2000-02-01 to 2000-02-last,
810 day list right,month label above centered];
811 \end{codeexample}
812 %
813 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
814 \tikz
815 \calendar [dates=2000-01-20 to 2000-02-10,
816 week list,month label above centered];
817 \end{codeexample}
818 %
819 \end{stylekey}
820
821 \begin{stylekey}{/tikz/month label above right}
822 Works as above, but flushed right
823 %
824 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
825 \tikz
826 \calendar [dates=2000-01-20 to 2000-02-10,
827 week list,month label above right];
828 \end{codeexample}
829 %
830 \end{stylekey}
831
832 \begin{stylekey}{/tikz/month label below left}
833 Works like |month label above left|, only the label is placed below the
834 row. This placement is not really useful with the |week list| arrangement,
835 but rather with the |day list right| or |month list| arrangement.
836 %
837 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
838 \tikz
839 \calendar [dates=2000-02-01 to 2000-02-last,
840 day list right,month label below left];
841 \end{codeexample}
842 %
843 \end{stylekey}
844
845 \begin{stylekey}{/tikz/month label below centered}
846 Works like |month label above centered|, only below.
847 %
848 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
849 \tikz
850 \calendar [dates=2000-02-01 to 2000-02-last,
851 day list right,month label below centered];
852 \end{codeexample}
853 %
854 \end{stylekey}
855
856
857 \subsection{Examples}
858
859 In the following, some example calendars are shown that come either from real
860 applications or are just nice to look at.
861
862 Let us start with a year-2100-countdown, in which we cross out dates as we
863 approach the big celebration. For this, we set the shape to |strike out| for
864 these dates.
865 %
866 \begin{codeexample}[
867 leave comments,
868 preamble={\usetikzlibrary{calendar,shapes.misc}},
869 ]
870 \begin{tikzpicture}
871 \calendar
872 [
873 dates=2099-12-01 to 2100-01-last,
874 week list,inner sep=2pt,month label above centered,
875 month text=\%mt \%y0
876 ]
877 if (at most=2099-12-29) [nodes={strike out,draw}]
878 if (weekend) [black!50,nodes={draw=none}]
879 ;
880 \end{tikzpicture}
881 \end{codeexample}
882
883 The next calendar shows a deadline, which is 10 days in the future from the
884 current date. The last three days before the deadline are in red, because we
885 really should be done by then. All days on which we can no longer work on the
886 project are crossed out.
887 %
888 \begin{codeexample}[
889 leave comments,
890 preamble={\usetikzlibrary{calendar,shapes.misc}},
891 ]
892 \begin{tikzpicture}
893 \calendar
894 [
895 dates=\year-\month-\day+-25 to \year-\month-\day+25,
896 week list,inner sep=2pt,month label above centered,
897 month text=\textit{\%mt \%y0}
898 ]
899 if (at least=\year-\month-\day) {}
900 else [nodes={strike out,draw}]
901 if (at most=\year-\month-\day+7)
902 [green!50!black]
903 if (between=\year-\month-\day+8 and \year-\month-\day+10)
904 [red]
905 if (Sunday)
906 [gray,nodes={draw=none}]
907 ;
908 \end{tikzpicture}
909 \end{codeexample}
910
911 The following example is a futuristic calendar that is all about circles:
912 %
913 \begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
914 \sffamily
915
916 \colorlet{winter}{blue}
917 \colorlet{spring}{green!60!black}
918 \colorlet{summer}{orange}
919 \colorlet{fall}{red}
920
921 % A counter, since TikZ is not clever enough (yet) to handle
922 % arbitrary angle systems.
923 \newcount\mycount
924
925 \begin{tikzpicture}
926 [transform shape,
927 every day/.style={anchor=mid,font=\fontsize{6}{6}\selectfont}]
928 \node{\normalsize\the\year};
929 \foreach \month/\monthcolor in
930 {1/winter,2/winter,3/spring,4/spring,5/spring,6/summer,
931 7/summer,8/summer,9/fall,10/fall,11/fall,12/winter}
932 {
933 % Compute angle:
934 \mycount=\month
935 \advance\mycount by -1
936 \multiply\mycount by 30
937 \advance\mycount by -90
938
939 % The actual calendar
940 \calendar at (\the\mycount:6.4cm)
941 [
942 dates=\the\year-\month-01 to \the\year-\month-last,
943 ]
944 if (day of month=1) {\color{\monthcolor}\tikzmonthcode}
945 if (Sunday) [red]
946 if (all)
947 {
948 % Again, compute angle
949 \mycount=1
950 \advance\mycount by -\pgfcalendarcurrentday
951 \multiply\mycount by 11
952 \advance\mycount by 90
953 \pgftransformshift{\pgfpointpolar{\mycount}{1.4cm}}
954 };
955 }
956 \end{tikzpicture}
957 \end{codeexample}
958
959 Next, let's us have a whole year in a tight column:
960 %
961 \begin{codeexample}[leave comments,preamble={\usetikzlibrary{calendar}}]
962 \begin{tikzpicture}
963 \small\sffamily
964 \colorlet{darkgreen}{green!50!black}
965 \calendar[dates=\year-01-01 to \year-12-31,week list,
966 month label left,month yshift=0pt,
967 month text=\textcolor{darkgreen}{\%m0}]
968 if (Sunday) [black!50];
969 \end{tikzpicture}
970 \end{codeexample}
971
972
973 %%% Local Variables:
974 %%% mode: latex
975 %%% TeX-master: "pgfmanual-pdftex-version"
976 %%% End: