3Implementation¶

3.1Packages¶

pgfgantt is modest in terms of dependencies: It only requires the TikZ and pgfcalendar packages.

3.2Macros for Key and Error Management¶

\@gtt@ifstar reimplements the LaTeX2ε kernel’s \@ifstar macro. This makes it robust to amsgen’s reimplementation of \@ifstar.

\ganttset changes the current key path to /pgfgantt/ and then executes the keys in its mandatory argument.

The following auxiliary macros save us some code when we devise keys later on. \@gtt@keydef{⟨key⟩}{⟨initial value⟩} declares the key /pgfgantt/⟨key⟩ and stores its ⟨initial value⟩.

\ganttvalueof{⟨key⟩} retrieves the value stored by a ⟨key⟩. Link type authors should be able to use this macro in their code; thus, it lacks any @s.

\@gtt@stylekeydef{⟨key⟩}{⟨initial style⟩} declares a style ⟨key⟩ with an ⟨initial style⟩.

\@gtt@PackageError{⟨message⟩} and \@gtt@PackageWarning{⟨message⟩} issue a package error or warning ⟨message⟩, respectively.

3.3The Horizontal and Vertical Grid¶

The count register \gtt@currentline holds the current line; it starts from 0 and decreases. \gtt@lasttitleline equals the line of the title element drawn last. \gtt@currgrid is the index of the current grid line drawn. \gtt@chartwidth equals the number of time slots.

hgrid checks whether its value is false and sets the boolean \ifgtt@hgrid accordingly. If the value is true or missing, horizontal grid lines appear dotted.

The \gtt@hgrid@do macro decomposes the style list for the horizontal grid into its comma-separated items. Each item is analyzed (see below) only if some grid lines are still left to draw. Note the “elegant” quadruple \expandafter construction, which enables tail recursion.

In the absence of a star as the first token in a style list item, \gtt@hgrid@analyze adds the multiplier 1 to the input stream.

\gtt@hgrid@draw draws as many grid lines as required by the multiplier. It increases \gtt@currgrid after each line drawn and breaks the loop as soon as all grid rules have been drawn.

Analogously, we declare options and macros for printing the vertical grid.

3.4Time Slot Formats¶

\gtt@smugglecount{⟨count⟩} smuggles the local value of a count register over the end of a TeX group.

\gtt@juliantotimeslot{⟨count 1⟩}{⟨count 2⟩} converts the Julian date stored in ⟨count 1⟩ to a time slot and stores the latter in ⟨count 2⟩. This macro is called after the start of Gantt chart. Thus, \gtt@startyear, \gtt@startmonth and \gtt@startjulian (see section 3.5) have already been initialized. Depending on the value of time slot unit, one time slot corresponds to one day, one month or one year.

\newgantttimeslotformat{⟨name⟩}{⟨code⟩} defines the macro
\gtt@tsstojulian@⟨name⟩{⟨tss⟩}{⟨count⟩}. This macro executes ⟨code⟩ (within a group), which should convert ⟨tss⟩ to a Julian date and store the date in ⟨count⟩.

The predefined time slot formats simple, isodate, isodate-yearmonth and isodate-year are straight forward.

\gtt@tsf@getdmy{⟨date⟩} decomposes a ⟨date⟩ day[sep]month[sep]year (with [sep] representing a period, hyphen or slash) into day, month and year and stores these numbers in \local@day, \local@month and \local@year, respectively.

Time slot formats little-endian, big-endian and middle-endian only differ in their call of \pgfcalendardatetojulian. If the year (stored in \local@year or \local@day) lacks a century (e. g., 13 instead of 2013), it is completed according to the value of time slot format/base century.

The key time slot format=⟨name⟩ checks whether the format ⟨name⟩ exists and then defines the macro \gtt@tsstojulian to be equivalent to
\gtt@tsstojulian@⟨name⟩.

time slot format/base century=⟨year⟩ extracts the century from the four-digit ⟨year⟩ (e. g., 20 from 2000) and stores it in \gtt@tsf@basecentury.

time slot format/start date=⟨isodate⟩ stores the Julian date corresponding to ⟨isodate⟩ in \gtt@tsf@startjulian.

3.5The Main Environment¶

Keys that store the basis vectors of the chart.

Keys related to the canvas and the today rule.

Boolean key that determines if \\ is equivalent to \ganttnewline.

The boolean \ifgtt@tikzpicture is true if a Gantt chart appears within a TikZ picture. \ifgtt@intitle is true at the start of a ganttchart environment and set to false as soon as the first non-title element is encountered. \gtt@lasttitleslot corresponds to the \(x\)-coordinate of its right border. \gtt@elementid enumerates the automatic names of chart elements. \gtt@today@slot is the time slot of the today rule. \gtt@startjulian and \gtt@endjulian contain the Julian dates corresponding to the first and last time slot, respectively. \gtt@chartid assigns a consecutive number to each chart.

Each ganttchart environment writes a \gtt@chartextrasize{⟨chart id⟩}{⟨extra size⟩} macro to the auxililary file. This macro stores its second argument in a macro of the form \@gtt@chart@⟨chart id⟩@extrasize. The ⟨extra size⟩ is the size of the chart’s bounding box less the size of the canvas, calculated as x unit times the number of time slots.

At the beginning of a ganttchart environment, the keys in its optional argument are executed. Initialize the macros and counts that contain start dates, end dates, the chart width, …

… the time slot of the today rule, ….

… the current element number, and information for drawing actions.

If expand chart contains a value different from none, scale the chart so that its \(x\)-extent equals this value. To this end, use the information stored in the auxiliary file. \gtt@expanded@xunit will contain the new value for x unit.

If a ganttchart appears outside of a tikzpicture, we implicitly start this environment. “Within a tikzpicture” means that \useasboundingbox is defined. Since we expect a chart to start with at least one title element, \ifgtt@intitle is true. If newline shortcut is true, make the control symbol \\ equivalent to \ganttnewline. In any case, \ganttalignnewline is defined.

After the contents of the environment have been drawn, we add the canvas to the background layer. pgfgantt saves \(x\)- and \(y\)-coordinates in local internal macros called \x@left, \x@right, \x@mid, \x@size, \y@upper, \y@lower, \y@mid and \y@size.

The contents of the vertical grid style list are evaluated at most \gtt@chartwidth-times, but the loop breaks as soon as all grid lines have been drawn.

Now, we draw the horizontal grid. If we exclude the title from the canvas, we omit the uppermost horizontal grid line since it would coincide with the canvas border.

The last task of ganttchart is to apply the today key if its value differs from none.

Store the \(x\)-extent of the bounding box in \@tempdima. Calculate the size by which the bounding box exceeds the “raw” canvas size. Write this information to the auxiliary file.

Increase the chart counter.

At the end of a ganttchart, we also close the tikzpicture if we started it implicitly.

3.6Starting a New Line¶

Unless the optional argument of \ganttnewline is empty, this macro adds a horizontal grid rule between the current and the new line. The style of this line, which is stored in \local@drawarg, is either hgrid style or the style specified in the optional argument. Anyway, \ganttnewline decreases \gtt@currentline and, if we are still in the title, \gtt@lasttitleline. Since the new line starts at time slot zero, \gtt@lasttitleslot is reset.

3.7Vertical rules¶

Keys related to the vertical rules.

A count for storing the vrule time slot.

Calculate the coordinates for the vertical rule and draw it.

3.8Titles¶

Keys that influence title elements. The parameter token #1 in the value of title label text is replaced by the argument of \gtt@titlelabeltext. Note that \@gtt@keydef cannot define title list options, since \@gtt@titlelistoptions is expanded after a \foreach statement, where \ganttvalueof will not work.

Keys for title calendars.

\gantttitle draws a title element (i. e., a rectangle with a single node at its center). For reasons that will become clear below, the element essentially starts at the \(x\)-coordinate stored in \gtt@lasttitleslot. This count is updated at the end of the macro.

\gantttitlelist generates title elements by repeatedly calling \gantttitle. Since the latter always starts after the last time slot occupied by the previous element, \gantttitlelist does not have to calculate the respective \(x\)-coordinates explicitly.

\gantttitlecalendar checks whether it is invoked in the starred or nonstarred form, sets \ifgtt@titlecalendarstar accordingly and then starts a command relaying chain.

The first command in the relaying chain, \@gantttitlecalendar[⟨options⟩], processes the ⟨options⟩. If it was executed by the starred form of \gantttitlecalendar, it calls the second command in the chain. Otherwise, it directly calls the third command in the chain.

The second command in the relaying chain,
\@@gantttitlecalendar{⟨start tss⟩}{⟨end tss⟩},
reads two mandatory arguments from the input stream and converts them to Julian dates. Finally, it calls the third command in the chain.

The third and last command in the relaying chain, \@@@gantttitlecalendar{⟨start Julian⟩}{⟨end Julian⟩}{⟨calendar lines⟩}, stores the start and end ISO-standard dates of the calendar in \gtt@calendar@startdate and \gtt@calendar@enddate, respectively. Then, it executes the keys in ⟨calendar lines⟩, which reside in path /pgfgantt/calendar.

Booleans and counts for drawing title calendars: \ifgtt@calendar@eol is true if \ganttcalendar should start a new calendar line. \gtt@calendar@slots is the number of time slots a calendar element will cover. \gtt@calendar@weeknumber is the current week number in a calendar line of type week. \gtt@calendar@startofweek is the Julian date of the Monday in the current week.

\@gtt@getfourthdigit returns the fourth digit of a year, while \@gtt@getdecade returns the first three digits of a year.

We define a new check for \pgfcalendarifdate as described in the pgfcalendar manual: end of decade=⟨date⟩ returns true if a date marks the end of a decade as defined by ⟨date⟩. For instance, if ⟨date⟩ is 2009-12-31, then the conditional will be true for the dates 1999-12-31, 2009-12-31, 2019-12-31 and so on.

For each ⟨line type⟩, we define a corresponding key /pgfgantt/calendar/⟨line type⟩. This key performs the necessary calculations and draws one or several \gantttitles. Line type decade draws decades.

Line type year draws years.

Line type month=⟨format⟩ draws months. Internally, a month is represented by a number between 1 (January) and 12 (December). However, when the title element is drawn, this number is fed to the macro \pgfcalendarmonth⟨format⟩ and possibly converted.

Line type week=⟨number⟩ draws weeks. The first week receives ⟨number⟩, which is also saved in \currentweek. This key also defines the macros \startyear, \startmonth and \startday, which store the year, month and day of the current week’s Monday. These four macros can be used in the value of calendar week text.

Line type weekday=⟨format⟩ draws weekdays. Internally, a weekday is represented by a number between 0 (Monday) and 6 (Sunday). However, when the title element is drawn, this number is fed to the macro \pgfcalendarweekday⟨format⟩ and possibly converted.

Line type day=⟨format⟩ draws days of the month.

3.9Chart Elements¶

Keys that apply to all chart elements. The parameter token #1 in the value of progress label text is replaced by the argument of \gtt@progresslabeltext.

The macros \gtt@lastelement and \gtt@currentelement save the name of the current and last chart element drawn. Thereby, the \ganttlinked... macros can add a link connecting them. \ifgtt@draw@complete, \ifgtt@draw@incomplete and \ifgtt@draw@clip decide whether to draw the complete and incomplete part of a chart element and if these parts are clipped. \gtt@left@slot and \gtt@right@slot store a chart element’s start and end time slot, respectively.

\gtt@chartelement[⟨options⟩]{⟨label⟩}{⟨start tss⟩}{⟨end tss⟩}{⟨type⟩}
is the generic command for drawing chart elements of a certain ⟨type⟩. First, \gtt@chartelement converts ⟨start tss⟩ to \gtt@left@slot and ⟨end tss⟩ to \gtt@right@slot. Then it calculates the usual coordinates. \gtt@name stores the name of the chart element.

Depending on the values of progress and today, we determine the correct value for \gtt@progress. A value between 0 and 100 corresponds to a percentage of completeness. A value of 999 indicates that the chart element has no associated progress.

Now we determine whether only the complete part of the chart element, only its incomplete one or both are drawn. In the former two cases, we refrain from clipping the (in)complete part.

We draw the chart element within a pgfinterruptboundingbox, since we clip a large area of the canvas in order to avoid removing parts of the chart element border.

If progress differs from none and progress label text differs from \relax, the progress label is drawn.

If ⟨label⟩ is not empty, a label is printed. Its anchor is either at the ⟨type⟩ inline label anchor of the chart element (inline=true) or at the left canvas border halfway between the upper and lower \(y\)-coordinate of the chart element (inline=false).

Since the first bar clearly appears after the last line containing a title element, we set the boolean \ifgtt@intitle to false.

\newganttchartelement checks whether it was invoked in the starred or nonstarred form and executes \@newganttchartelement@one or \@newganttchartelement@two, respectively.

Both \@newganttchartelement@one{⟨type⟩} and ...two{⟨type⟩} define two macros \gantt⟨type⟩ and \ganttlinked⟨type⟩, which draw a singular chart element or one that is linked to its predecessor. However, the newly defined macros will take three or four mandatory arguments (cf. \ganttmilestone vs. \ganttbar). At the end, we execute \@newganttchartelement@definekeys to process the second mandatory argument of \newganttchartelement.

\@newganttchartelement@definekeys{⟨type⟩}{⟨key-value list⟩} introduces 14 keys for the newly generated chart element ⟨type⟩.

Code for the predefined chart element type bar.

Code for the predefined chart element type group.

More keys for the appearance of groups.

Code for the predefined chart element type milestone.

3.10Node Shapes¶

Keys for configuring the additional anchors of the new node shapes.

Code for node shape ganttbar. Anchors and background path derive from node shape rectangle. The four additional anchors on top, on bottom, on left and on right are defined.

Code for node shape ganttgroup. Anchors derive from node shape ganttbar. The two additional anchors left peak and right peak are defined.

Code for node shape ganttmilestone. Anchors and background path derive from node shape diamond. The four additional anchors on top, on bottom, on left and on right are defined.

3.11Links¶

Keys for configuring links.

\newganttlinktype{⟨type⟩}{⟨code⟩} stores ⟨code⟩ in an internal macro
\@gtt@linktype@⟨type⟩, which is later called by \gtt@drawlink.

\setganttlinklabel{⟨type⟩}{⟨label⟩} stores a given ⟨label⟩ in an internal macro \@gtt@linktype@⟨type⟩@label, which is later used by \gtt@drawlink.

\newganttlinktypealias{⟨new link type⟩}{⟨existing link type⟩} copies both the link code and label of an ⟨existing link type⟩ into the internal macros associated with a ⟨new link type⟩.

We will define three link subtypes for the type auto, which require the following keys:

(1) r (short for “right”) draws a straight arrow. Note that r and default are alias types.

(2) rdr (“right-down-right”) is an unlabeled three-part arrow. The value of link mid sets the position of the middle segment.

(3) rdldr (“right-down-left-down-right”) is an unlabeled five-part arrow, which considers the values of link bulge and link mid.

Now we may define linke type auto: The first and last coordinate of the link should touch the preceding or following element at the center of its right or left border, respectively. We check if the connected elements lie in the same row or not (i. e., their \(y\)-coordinates differ at most 1 pt). In the latter case, \pgfmathparse yields 0.

Once again, two possibilities arise: Either the elements to be connected are at least separated by link tolerance time slots, in which case we draw a three-part arrow (i. e., link type rdr). Alternatively, the elements lie in adjacent time slots or even overlap, in which case we draw a five-part arrow (i. e., link type rdldr).

For elements that lie in the same row, we draw a simple arrow (i. e., link type r).

The dr type is explained in section 2.9.

Here is the definition of the four straight link types and their labels.

\gtt@drawlink{⟨link type⟩} first checks if the ⟨link type⟩ is defined, falling back to type default if it is unknown. \@gtt@currlinktype stores the link type for future reference.

If the link label key contains any value, it locally overrides the label set by \setganttlinklabel. \ganttlinklabel is defined accordingly.

Finally, we call the internal macro that stores the code for the desired link type.

We need the following keys for setting the start and end anchor of a link: Whenever a key /pgfgantt/link anchor/⟨anchor⟩ is undefined, pgfgantt stores ⟨anchor⟩ in \@gtt@link@anchor.

\@gtt@linkanchordef{⟨anchor⟩} deals with the anchors on top etc.: It creates a code key /pgfgantt/link anchor/⟨anchor⟩, which stores its own name in \@gtt@link@anchor and sets the appropriate …fraction key.

\@gtt@setstartanchor{⟨anchor⟩} recalls the coordinates of the anchor stored in \@gtt@link@anchor from chart element \@gtt@link@startelement. It stores these coordinates in the auxiliary macros \xLeft and \yUpper.

\@gtt@setendanchor{⟨anchor⟩} is similar to the command above. However, it stores the anchor coordinates in the auxiliary macros \xRight and \yLower.

\ganttlink[⟨options⟩]{⟨E1⟩}{⟨E2⟩} executes the ⟨options⟩ and stores the names of the connected elements ⟨E1⟩ and ⟨E2⟩ in \@gtt@link@startelement and \@gtt@link@endelement.

\ganttsetstartanchor and \ganttsetendanchor are only valid in the second argument of \newganttlinktype. Since you may wish to omit one of those commands, we set default anchors for the link.

We call \gtt@drawlink with the value of link type.