diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-09 00:56:57 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-09 00:56:57 +0000 |
commit | f07bb53970ee2ecc53f81a206a3d3a67ef665e4a (patch) | |
tree | 6f57a1d62971db79e5ff023bdfd83b22cb971dc9 /Master/texmf-dist/doc/generic/pgf/text-en | |
parent | 007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 (diff) |
doc 6
git-svn-id: svn://tug.org/texlive/trunk@85 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en')
52 files changed, 19245 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex new file mode 100644 index 00000000000..f0e0f45c061 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex @@ -0,0 +1,465 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Using Paths} + +\subsection{Overview} + +Once a path has been constructed, it can be \emph{used} in different +ways. For example, you can draw the path or fill it or use it for +clipping. + +Numerous graph parameters influence how a path will be rendered. For +example, when you draw a path, the line width is important as well as +the dashing pattern. The options that govern how paths are rendered +can all be set with commands starting with |\pgfset|. \emph{All + options that influence how a path is rendered always influence the + complete path.} Thus, it is not possible to draw part of a path +using, say, a red color and drawing another part using a green +color. To achieve such an effect, you must use two paths. + +In detail, paths can be used in the following ways: + +\begin{enumerate} +\item + You can \emph{stroke} (also known as \emph{draw}) a path. +\item + You can \emph{fill} a path with a uniform color. +\item + You can \emph{clip} subsequent renderings against the path. +\item + You can \emph{shade} a path. +\item + You can \emph{use the path as bounding box} for the whole picture. +\end{enumerate} +You can also perform any combination of the above, though it makes no +sense to fill and shade a path at the same time. + +To perform (a combination of) the first three actions, you can use the +following command: +\begin{command}{\pgfusepath\marg{actions}} + Applies the given \meta{actions} to the current path. Afterwards, + the current path is (globally) empty. The following actions are + possible: + \begin{itemize} + \item \declare{|fill|} + fills the path. See Section~\ref{section-fill} for further details. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} + \item \declare{|stroke|} + strokes the path. See Section~\ref{section-stroke} for further details. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + \item \declare{|clip|} + clips all subsequent drawings against the path. See + Section~\ref{section-clip} for further details. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke,clip} + \pgfpathcircle{\pgfpoint{1cm}{1cm}}{0.5cm} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} + \item \declare{|discard|} + discards the path, that is, it is not used at all. Giving this + option (alone) has the same effect as giving an empty options + list. + \end{itemize} + When more than one of the first three actions are given, they are + applied in the above ordering, regardless of their ordering in + \meta{actions}. Thus, |{stroke,fill}| and |{fill,stroke}| have the + same effect. +\end{command} + +To shade a path, use the |\pgfshadepath| command, which is explained +in Section~\ref{section-shadings}. + + + +\subsection{Stroking a Path} +\label{section-stroke} + +When you use |\pgfusepath{stroke}| to stroke a path, several graphic +parameters influence how the path is drawn. The commands for setting +these parameters are explained in the following. + +Note that all graphic parameters apply to the path as a whole, never +only to a part of it. + +All graphic parameters are local to the current |{pgfscope}|, but they +persists past \TeX\ groups, \emph{except} for the interior rule +(even-odd or nonzero) and the arrow tip kinds. The latter graphic +parameters only persist till the end of the current \TeX\ group, but +this may change in the future, so do not count on this. + +\subsubsection{Graphic Parameter: Line Width} + +\begin{command}{\pgfsetlinewidth\marg{line width}} + This command sets the line width for subsequent strokes (in the + current |pgfscope|). The line width is given as a normal \TeX\ + dimension like |0.4pt| or |1mm|. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetlinewidth{1mm} + \pgfpathmoveto{\pgfpoint{0mm}{0mm}} + \pgfpathlineto{\pgfpoint{2cm}{0mm}} + \pgfusepath{stroke} + \pgfsetlinewidth{2\pgflinewidth} % double in size + \pgfpathmoveto{\pgfpoint{0mm}{5mm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{textoken}{\pgflinewidth} + You can access the current line width via the \TeX\ dimension + |\pgflinewidth|. It will be set to the correct line width, that is, + even when a \TeX\ group closed, the value will be correct since it + is set globally, but when a |{pgfscope}| closes, the value is set to + the correct value it had before the scope. +\end{textoken} + + +\subsubsection{Graphic Parameter: Caps and Joins} + +\begin{command}{\pgfsetbuttcap} + Sets the line cap to a butt cap. See Section~\ref{section-cap-joins} + for an explanation of what this is. +\end{command} +\begin{command}{\pgfsetroundcap} + Sets the line cap to a round cap. See again + Section~\ref{section-cap-joins}. +\end{command} +\begin{command}{\pgfsetrectcap} + Sets the line cap to a square cap. See again + Section~\ref{section-cap-joins}. +\end{command} +\begin{command}{\pgfsetroundjoin} + Sets the line join to a round join. See again + Section~\ref{section-cap-joins}. +\end{command} +\begin{command}{\pgfsetbeveljoin} + Sets the line join to a bevel join. See again + Section~\ref{section-cap-joins}. +\end{command} +\begin{command}{\pgfsetmiterjoin} + Sets the line join to a miter join. See again + Section~\ref{section-cap-joins}. +\end{command} +\begin{command}{\pgfsetmiterlimit\marg{miter limit factor}} + Sets the miter limit to \meta{miter limit factor}. See again + Section~\ref{section-cap-joins}. +\end{command} + +\subsubsection{Graphic Parameter: Dashing} + +\begin{command}{\pgfsetdash\marg{list of even length of dimensions}\marg{phase}} + Sets the dashing of a line. The first entry in the list specifies + the length of the first solid part of the list. The second entry + specifies the length of the following gap. Then comes the length of + the second solid part, following by the length of the second gap, + and so on. The \meta{phase} specifies where the first solid part + starts relative to the beginning of the line. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0cm} + \pgfpathmoveto{\pgfpoint{0mm}{0mm}} + \pgfpathlineto{\pgfpoint{2cm}{0mm}} + \pgfusepath{stroke} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.1cm} + \pgfpathmoveto{\pgfpoint{0mm}{1mm}} + \pgfpathlineto{\pgfpoint{2cm}{1mm}} + \pgfusepath{stroke} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.2cm} + \pgfpathmoveto{\pgfpoint{0mm}{2mm}} + \pgfpathlineto{\pgfpoint{2cm}{2mm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + + Use |\pgfsetdash{}{0pt}| to get a solid dashing. +\end{command} + +\subsubsection{Graphic Parameter: Stroke Color} + +\begin{command}{\pgfsetstrokecolor\marg{color}} + Sets the color used for stroking lines to \meta{color}, where + \meta{color} is a \LaTeX\ color like |red| or |black!20!red|. Unlike + the |\color| command, the effect of this command lasts till the end + of the current |{pgfscope}| and not till the end of the current + \TeX\ group. + + The color used for stroking may be different from the color used for + filling. However, a |\color| command will always ``immediately + override'' any special settings for the stroke and fill colors. + + In plain \TeX, this command will also work, but the problem of + \emph{defining} a color arises. After all, plain \TeX\ does not + provide \LaTeX\ colors. For this reason, \pgfname\ implements a + minimalistic ``emulation'' of the |\definecolor|, |\colorlet|, and + |\color| commands. Only gray-scale and rgb colors are supported. For + most cases this turns out to be enough. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetlinewidth{1pt} + \color{red} + \pgfpathcircle{\pgfpoint{0cm}{0cm}}{3mm} \pgfusepath{fill,stroke} + \pgfsetstrokecolor{black} + \pgfpathcircle{\pgfpoint{1cm}{0cm}}{3mm} \pgfusepath{fill,stroke} + \color{red} + \pgfpathcircle{\pgfpoint{2cm}{0cm}}{3mm} \pgfusepath{fill,stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetcolor\marg{color}} + Sets both the stroke and fill color. The difference to the normal + |\color| command is that the effect lasts till the end of the + current |{pgfscope}|, not only till the end of the current \TeX\ + group. +\end{command} + + +\subsubsection{Graphic Parameter: Stroke Opacity} + +\begin{command}{\pgfsetstrokeopacity\marg{value}} + Sets the opacity of stroking operations. The \meta{value} should be + a number between |0| and |1|, where |1| means ``fully opaque'' and + |0| means ``fully transparent.'' A value like |0.5| will cause paths + to be stroked in a semitransparent way. + + \emph{Note:} For PostScript output, opacity is rendered correctly + only with the most recent versions of GhostScript. Printers and + other programs will ignore the opacity setting. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetlinewidth{5mm} + \color{red} + \pgfpathcircle{\pgfpoint{0cm}{0cm}}{10mm} \pgfusepath{stroke} + \color{black} + \pgfsetstrokeopacity{0.5} + \pgfpathcircle{\pgfpoint{1cm}{0cm}}{10mm} \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + + +\subsubsection{Graphic Parameter: Arrows} + +After a path has been drawn, \pgfname\ can add arrow tips at the +ends. Currently, it will only add arrows correctly at the end of paths +that consist of a single open part. For other paths, like closed paths +or path consisting of multiple parts, the result is not defined. + +\begin{command}{\pgfsetarrowsstart\marg{arrow kind}} + Sets the arrow tip kind used at the start of a (possibly curved) + path. When this option is used, the line will often be slightly + shortened to ensure that the tip of the arrow will exactly ``touch'' + the ``real'' start of the line. + + To ``clear'' the start arrow, say |\pgfsetarrowsstart{}|. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetarrowsstart{latex} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \pgfsetarrowsstart{to} + \pgfpathmoveto{\pgfpoint{0cm}{2mm}} + \pgfpathlineto{\pgfpoint{1cm}{2mm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + + The effect of this command persists only till the end of the current + \TeX\ scope. + + The different possible arrow kinds are explained in + Section~\ref{section-arrows}. +\end{command} + +\begin{command}{\pgfsetarrowsend\marg{arrow kind}} + Sets the arrow tip kind used at the end of a path. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetarrowsstart{latex} + \pgfsetarrowsend{to} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetarrows{\texttt{\char`\{}}\meta{start kind}|-|\meta{end kind}{\texttt{\char`\}}}} + Sets the start arrow kind to \meta{start kind} and the end kind to + \meta{end kind}. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetarrows{latex-to} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetshortenstart\marg{dimension}} + This command will shortened the start of every stroked path by the + given dimension. This shortening is done in addition to automatic + shortening done by a start arrow, but it can be used even if no + start arrow is given. + + This command is useful if you wish arrows or lines to ``stop shortly + before'' a given point. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathcircle{\pgfpointorigin}{5mm} + \pgfusepath{stroke} + \pgfsetarrows{latex-} + \pgfsetshortenstart{4pt} + \pgfpathmoveto{\pgfpoint{5mm}{0cm}} % would be on the circle + \pgfpathlineto{\pgfpoint{2cm}{0cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetshortenend\marg{dimension}} + Works like |\pgfsetshortenstart|. +\end{command} + + + +\subsection{Filling a Path} +\label{section-fill} + +Filling a path means coloring every interior point of the path with +the current fill color. It is not always obvious whether a point is +``inside'' a path when the path is self-intersecting and/or consists +or multiple parts. In this case either the nonzero winding number rule +or the even-odd crossing number rule is used to decide, which points +lie ``inside.'' These rules are explained in +Section~\ref{section-rules}. + +\subsubsection{Graphic Parameter: Interior Rule} + +You can set which rule is used using the following commands: + +\begin{command}{\pgfseteorule} + Dictates that the even-odd rule is used in subsequent fillings in + the current \emph{\TeX\ scope}. Thus, for once, the effect of this + command does not persist past the current \TeX\ scope. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfseteorule + \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} + \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetnonzerorule} + Dictates that the nonzero winding number rule is used in subsequent + fillings in the current \TeX\ scope. This is the default. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetnonzerorule + \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} + \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\subsubsection{Graphic Parameter: Filling Color} + +\begin{command}{\pgfsetfillcolor\marg{color}} + Sets the color used for filling paths to \meta{color}. Like the + stroke color, the effect lasts only till the next use of |\color|. +\end{command} + + +\subsubsection{Graphic Parameter: Fill Opacity} + +\begin{command}{\pgfsetfillopacity\marg{value}} + Sets the opacity of filling operations. As for stroking, the + \meta{value} should be a number between |0| and~|1|. + + The ``filling transparency'' will also be used for text and images. + +\begin{codeexample}[] +\begin{tikzpicture} + \pgfsetfillopacity{0.5} + \fill[red] (90:1cm) circle (11mm); + \fill[green] (210:1cm) circle (11mm); + \fill[blue] (-30:1cm) circle (11mm); +\end{tikzpicture} +\end{codeexample} +\end{command} + +\subsection{Clipping a Path} +\label{section-clip} + +When you add the |clip| option, the current path is used for +clipping subsequent drawings. The same rule as for filling is used to +decide whether a point is inside or outside the path, that is, either +the even-odd rule or the nonzero rule. + +Clipping never enlarges the clipping area. Thus, when you clip against +a certain path and then clip again against another path, you clip +against the intersection of both. + +The only way to enlarge the clipping path is to end the |{pgfscope}| +in which the clipping was done. At the end of a |{pgfscope}| the +clipping path that was in force at the beginning of the scope is +reinstalled. + +\subsection{Using a Path as a Bounding Box} +\label{section-using-bb} + +When you add the |use as bounding box| option, the bounding box of the +picture will be enlarged such that the path in encompassed, but any +\emph{subsequent} paths of the current \TeX\ scope will not have any +effect on the size of the bounding box. Typically, you use this +command at the very beginning of a |{pgfpicture}| environment. + +\begin{codeexample}[] +Left +\begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}} + \pgfusepath{use as bounding box} % draws nothing + + \pgfpathcircle{\pgfpointorigin}{2ex} + \pgfusepath{stroke} +\end{pgfpicture} +right. +\end{codeexample} + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex new file mode 100644 index 00000000000..078a929d4e3 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex @@ -0,0 +1,677 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Arrow Tips} +\label{section-arrows} + + +\subsection{Overview} + +\subsubsection{When Does PGF Draw Arrow Tips?} + +\pgfname\ offers an interface for placing \emph{arrow tips} at the end +of lines. The interface works as follows: + +\begin{enumerate} +\item + You (or someone else) assigns a name to a certain kind of arrow + tips. For example, the + arrow tip |latex| is the arrow tip used by the standard \LaTeX\ + picture environment; the arrow tip |to| looks like the tip of the + arrow in \TeX's |\to| command; and so on. + + This is done once at the beginning of the document. +\item + Inside some picture, at some point you specify that in the current + scope from now on you would like tips of, say, kind |to| to be added + at the end and/or beginning of all paths. + + When an arrow kind has been installed and when \pgfname\ is about to + stroke a path, the following things happen: + \begin{enumerate} + \item + The beginning and/or end of the path is shortened appropriately. + \item + The path is stroked. + \item + The arrow tip is drawn at the beginning and/or end of the path, + appropriately rotated and appropriately resized. + \end{enumerate} +\end{enumerate} + +In the above description, there are a number of ``appropriately.'' +The exact details are not quite trivial and described later on. + +\subsubsection{Meta-Arrow Tips} + +In \pgfname, arrows are ``meta-arrows'' in the same way that fonts in +\TeX\ are ``meta-fonts.'' When a meta-arrow is resized, it is not +simply scaled, but a possibly complicated transformation is applied to +the size. + +A meta-font is not one particular font at a specific size with a +specific stroke width (and with a large number of other parameters +being fixed). Rather, it is a ``blueprint'' (actually, more like a +program) for generating such a font at a particular size and +width. This allows the designer of a meta-font to make sure that, say, +the font is somewhat thicker and wider at very small sizes. To +appreciate the difference: Compare the following texts: ``Berlin'' and +``\tikz{\node [scale=2,inner sep=0pt,outer sep=0pt]{\tiny + Berlin};}''. The first is a ``normal'' text, the second is the tiny +version scaled by a factor of two. Obviously, the first look +better. Now, compare ``\tikz{\node [scale=.5,inner sep=0pt,outer + sep=0pt]{Berlin};}'' and ``{\tiny Berlin}''. This time, the normal +text was scaled down, while the second text is a ``normal'' tiny +text. The second text is easier to read. + +\pgfname's meta-arrows work in a similar fashion: The shape of an +arrow tip can vary according to the line width of the arrow tip is +used. Thus, an arrow tip drawn at a line width of 5pt will typically +\emph{not} be five times as large as an arrow tip of line width +1pt. Instead, the size of the arrow will get bigger only slowly as the +line width increases. + +To appreciate the difference, here are the |latex| and |to| arrows, as +drawn by \pgfname\ at four different sizes: + +\medskip +\begin{tikzpicture} + \draw[-latex,line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; + \draw[-latex,line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; + \draw[-latex,line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; + \draw[-latex,line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; + + \draw[-to,line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; + \draw[-to,line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; + \draw[-to,line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; + \draw[-to,line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; +\end{tikzpicture} + +\medskip +Here, by comparison, is the same arrow when it is simply ``resized'' +(as done by most programs): + +\pgfarrowsdeclare{bad latex}{bad latex} +{ + \pgfarrowsleftextend{-1\pgflinewidth} + \pgfarrowsrightextend{9\pgflinewidth} +} +{ + \pgfpathmoveto{\pgfpoint{9\pgflinewidth}{0pt}} + \pgfpathcurveto + {\pgfpoint{6.3333\pgflinewidth}{.5\pgflinewidth}} + {\pgfpoint{2\pgflinewidth}{2\pgflinewidth}} + {\pgfpoint{-1\pgflinewidth}{3.75\pgflinewidth}} + \pgfpathlineto{\pgfpoint{-1\pgflinewidth}{-3.75\pgflinewidth}} + \pgfpathcurveto + {\pgfpoint{2\pgflinewidth}{-2\pgflinewidth}} + {\pgfpoint{6.3333\pgflinewidth}{-.5\pgflinewidth}} + {\pgfpoint{9\pgflinewidth}{0pt}} + \pgfusepathqfill +} + +\pgfarrowsdeclare{bad to}{bad to} +{ + \pgfarrowsleftextend{-2\pgflinewidth} + \pgfarrowsrightextend{\pgflinewidth} +} +{ + \pgfsetlinewidth{0.8\pgflinewidth} + \pgfsetdash{}{0pt} + \pgfsetroundcap + \pgfsetroundjoin + \pgfpathmoveto{\pgfpoint{-3\pgflinewidth}{4\pgflinewidth}} + \pgfpathcurveto + {\pgfpoint{-2.75\pgflinewidth}{2.5\pgflinewidth}} + {\pgfpoint{0pt}{0.25\pgflinewidth}} + {\pgfpoint{0.75\pgflinewidth}{0pt}} + \pgfpathcurveto + {\pgfpoint{0pt}{-0.25\pgflinewidth}} + {\pgfpoint{-2.75\pgflinewidth}{-2.5\pgflinewidth}} + {\pgfpoint{-3\pgflinewidth}{-4\pgflinewidth}} + \pgfusepathqstroke +} + +\medskip +\begin{tikzpicture} + \draw[-bad latex,line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; + \draw[-bad latex,line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; + \draw[-bad latex,line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; + \draw[-bad latex,line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; + + \draw[-bad to,line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; + \draw[-bad to,line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; + \draw[-bad to,line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; + \draw[-bad to,line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; +\end{tikzpicture} + +\bigskip +As can be seen, simple scaling produces arrow tips that are way too +large at larger sizes and way too small at smaller sizes. + + + +\subsection{Declaring an Arrow Tip Kind} + +To declare an arrow kind ``from scratch,'' the following command is +used: + +\begin{command}{\pgfarrowsdeclare\marg{start name}\marg{end + name}\marg{extend code}\marg{arrow tip code}} + This command declares a new arrow kind. An arrow kind has two names, + which will typically be the same. When the arrow tip needs to be + drawn, the \meta{arrow tip code} will be invoked, but the canvas + transformation is setup beforehand to a rotation such that when an + arrow tip pointing right is specified, the arrow tip that is + actually drawn points in the direction of the line. + + \medskip + \textbf{Naming the arrow kind.} + The \meta{start name} is the name + used for the arrow tip when it is at the start of a path, the \meta{end + name} is the name used at the end of a path. For example, the + arrow kind that looks like a parenthesis has the \meta{start + name} |(| and the \meta{end name} |)| so that you can say + |\pgfsetarrows{(-)}| to specify that you want parenthesis arrows and + both ends. + + The \meta{end name} and \meta{start name} can be quite arbitrary and + may contain spaces. + + \medskip + \textbf{Basics of the arrow tip code.} + Let us next have a look at the \meta{arrow tip code}. This code will + be used to draw the arrow tip when \pgfname\ thinks this is + necessary. The code should draw an arrow that ``points right,'' + which means that is should draw an arrow at the end of a line coming + from the left and ending at the origin. + + As an example, suppose we wanted to declare an arrow tip consisting + of two arcs, that is, we want the arrow tip to look more or less + like the red part of the following picture: +\begin{codeexample}[] +\begin{tikzpicture}[line width=3pt] + \draw (-2,0) -- (0,0); + \draw[red,join=round,cap=round] + (-10pt,10pt) arc (180:270:10pt) arc (90:180:10pt); +\end{tikzpicture} +\end{codeexample} + + We could use the following as \meta{arrow tip code} for this: +\begin{codeexample}[code only] +\pgfarrowsdeclare{arcs}{arcs}{...} +{ + \pgfsetdash{}{0pt} % do not dash + \pgfsetroundjoin % fix join + \pgfsetroundcap % fix cap + \pgfpathmoveto{\pgfpoint{-10pt}{10pt}} + \pgfpatharc{180}{270}{10pt} + \pgfpatharc{90}{180}{10pt} + \pgfusepathqstroke +} +\end{codeexample} + + Indeed, when the |...| is set appropriately (in a moment), we can + write the following: +\pgfarrowsdeclare{arcs}{arcs}{\pgfarrowsleftextend{0pt}\pgfarrowsrightextend{0pt}} +{ + \pgfsetdash{}{0pt} % do not dash + \pgfsetroundjoin % fix join + \pgfsetroundcap % fix cap + \pgfpathmoveto{\pgfpoint{-10pt}{10pt}} + \pgfpatharc{180}{270}{10pt} + \pgfpatharc{90}{180}{10pt} + \pgfusepathqstroke +} +\begin{codeexample}[] +\begin{tikzpicture} + \draw[-arcs,line width=3pt] (-2,0) -- (0,0); + \draw[arcs-arcs,line width=1pt] (-2,-1.5) -- (0,-1); + \useasboundingbox (-2,-2) rectangle (0,0.75); +\end{tikzpicture} +\end{codeexample} + + As can be seen in the second example, the arrow tip is automatically + rotated as needed when the arrow is drawn. This is achieved by a + canvas rotation. + + \medskip + \textbf{Special considerations about the arrow tip code.} + There are several things you need to be aware of when designing + arrow tip code: + \begin{itemize} + \item + Inside the code, you may not use the |\pgfusepath| + command. The reason is that this command internally calls arrow + construction commands, which is something you obviously do not want + to happen. + + Instead of |\pgfusepath|, use the quick versions. Typically, you + will use |\pgfusepathqstroke|, |\pgfusepathqfill|, or + |\pgfusepathqfillstroke|. + \item + The code will be executed only once, namely the first time the + arrow tip needs to be drawn. The resulting low-level driver + commands are protocoled and stored away. In all subsequent + uses of the arrow tip, the protocoled code is directly inserted. + \item + However, the code will be executed anew for each line width. Thus, + an arrow of line width 2pt may result in a different protocol than + the same arrow for a line width of 0.4pt. + \item + If you stroke the path that you construct, you should first set + the dashing to solid and setup fixed joins and caps, as + needed. This will ensure that the arrow tip will always look the + same. + \item + When the arrow tip code is executed, it is automatically put + inside a low-level scope, so nothing will ``leak out'' from the + scope. + \item + The high-level coordinate transformation matrix will be set to the + identity matrix when the code is executed for the first time. + \end{itemize} + + \medskip + \textbf{Designing meta-arrows.} + The \meta{arrow tip code} should adjust the size of the arrow in + accordance with the line width. For a small line width, the arrow + tip should be small, for a large line width, it should be + larger. However, the size of the arrow typically \emph{should not} + grow in direct proportion to the line width. On the other hand, the + size of the arrow head typically \emph{should} grow ``a bit'' with + the line width. + + For these reasons, \pgfname\ will not simply executed your arrow + code within a scaled scope, where the scaling depends on the line + width. Instead, your \meta{arrow tip code} is reexecuted again for + each different line width. + + In our example, we could use the following code for the new arrow + tip kind |arc'| (note the prime): +\begin{codeexample}[code only] +\newdimen\arrowsize +\pgfarrowsdeclare{arcs'}{arcs'}{...} +{ + \arrowsize=0.2pt + \advance\arrowsize by .5\pgflinewidth + \pgfsetdash{}{0pt} % do not dash + \pgfsetroundjoin % fix join + \pgfsetroundcap % fix cap + \pgfpathmoveto{\pgfpoint{-4\arrowsize}{4\arrowsize}} + \pgfpatharc{180}{270}{4\arrowsize} + \pgfpatharc{90}{180}{4\arrowsize} + \pgfusepathqstroke +} +\end{codeexample} +\newdimen\arrowsize +\pgfarrowsdeclare{arcs'}{arcs'}{\pgfarrowsleftextend{0pt}\pgfarrowsrightextend{0pt}} +{ + \arrowsize=0.2pt + \advance\arrowsize by .5\pgflinewidth + \pgfsetdash{}{0pt} % do not dash + \pgfsetroundjoin % fix join + \pgfsetroundcap % fix cap + \pgfpathmoveto{\pgfpoint{-4\arrowsize}{4\arrowsize}} + \pgfpatharc{180}{270}{4\arrowsize} + \pgfusepathqstroke + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharc{90}{180}{4\arrowsize} + \pgfusepathqstroke +} +\begin{codeexample}[] +\begin{tikzpicture} + \draw[-arcs',line width=3pt] (-2,0) -- (0,0); + \draw[arcs'-arcs',line width=1pt] (-2,-1.5) -- (0,-1); + \useasboundingbox (-2,-1.75) rectangle (0,0.5); +\end{tikzpicture} +\end{codeexample} + + However, sometimes, it can also be useful to have arrows that do not + resize at all when the line width changes. This can be achieved by + giving absolute size coordinates in the code, as done for |arc|. On + the other hand, you can also have the arrow resize linearly with the + line width by specifying all coordinates as multiples of + |\pgflinewidth|. + + \textbf{The left and right extend.} + Let us have another look at the exact left and right ``ends'' of our + arrow tip. Let us draw the arrow tip |arc'| at a very large size: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (-2,-1) grid (1,1); + \draw[line width=10pt,-arcs'] (-2,0) -- (0,0); + \draw[line width=2pt,white] (-2,0) -- (0,0); +\end{tikzpicture} +\end{codeexample} + + As one can see, the arrow tip does not ``touch'' the origin as it + should, but protrudes a little over the origin. One remedy to this + undesirable effect is to change the code of the arrow tip such that + everything is shifted half an |\arrowsize| to the left. While this + will cause the arrow tip to touch the origin, the line itself will + then interfere with the arrow: The arrow tip will be partly + ``hidden'' by the line itself. + + \pgfname\ uses a different approach to solving the problem: The + \meta{extend code} argument can be used to ``tell'' \pgfname\ how + much the arrow protrudes over the origin. The argument is also used + to tell \pgfname\ where the ``left'' end of the arrow is. However, + this number is important only when the arrow is being reversed or + composed with other arrow tips. + + Once \pgfname\ knows the right extend of an arrow kind, it can + \emph{shorten} lines by this amount when drawing arrows. + + Here is a picture that shows what the visualizes the extends. The + arrow tip itself is shown in red once more: + + \medskip + \begin{tikzpicture} + \draw[line width=1cm,-arcs',red] (-6,0) -- (0,0); + \draw[line width=1cm,black] (-6,0) -- (0,0); + \draw[help lines] (-6,0) -- (2,0) (0,-3) -- (0,3) coordinate (a); + \draw[help lines,xshift=0.5cm] (0,-3) -- (0,3) coordinate (b); + \draw[help lines,xshift=-2.5cm-0.8pt] (0,-3) -- (0,3) coordinate (c); + + \coordinate (xline 1) at (0,1.5); + \coordinate (xline 2) at (0,2.8); + + \draw[|->|] (xline 1 -| a) -- node[above=2pt] {right extend} (xline 1 -| b); + \draw[|<-|] (xline 2 -| c) -- node[above=2pt] {left extend} (xline 2 -| a); + + \draw (0,0) -- (1,-1) node[below right] {origin}; + \end{tikzpicture} + + + The \meta{extend code} is normal \TeX\ code that is executed + whenever \pgfname\ wants to know how far the arrow tip will protrude + to the right and left. The code should call the following two + commands: \declare{|\pgfarrowsrightextend|} and + \declare{|\pgfarrowsleftextend|}. Both arguments take one argument + that specifies the size. Here is the final code for the |arc''| arrow + tip: +\begin{codeexample}[] +\pgfarrowsdeclare{arcs''}{arcs''} +{ + \arrowsize=0.2pt + \advance\arrowsize by .5\pgflinewidth + \pgfarrowsleftextend{-4\arrowsize-.5\pgflinewidth} + \pgfarrowsrightextend{.5\pgflinewidth} +} +{ + \arrowsize=0.2pt + \advance\arrowsize by .5\pgflinewidth + \pgfsetdash{}{0pt} % do not dash + \pgfsetroundjoin % fix join + \pgfsetroundcap % fix cap + \pgfpathmoveto{\pgfpoint{-4\arrowsize}{4\arrowsize}} + \pgfpatharc{180}{270}{4\arrowsize} + \pgfusepathqstroke + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharc{90}{180}{4\arrowsize} + \pgfusepathqstroke +} +\begin{tikzpicture} + \draw[help lines] (-2,-1) grid (1,1); + \draw[line width=10pt,-arcs''] (-2,0) -- (0,0); + \draw[line width=2pt,white] (-2,0) -- (0,0); +\end{tikzpicture} +\end{codeexample} +\end{command} + +\pgfarrowsdeclare{arcs''}{arcs''} +{ + \arrowsize=0.2pt + \advance\arrowsize by .5\pgflinewidth + \pgfarrowsleftextend{-4\arrowsize-.5\pgflinewidth} + \pgfarrowsrightextend{.5\pgflinewidth} +} +{ + \arrowsize=0.2pt + \advance\arrowsize by .5\pgflinewidth + \pgfsetdash{}{0pt} % do not dash + \pgfsetroundjoin % fix join + \pgfsetroundcap % fix cap + \pgfpathmoveto{\pgfpoint{-4\arrowsize}{4\arrowsize}} + \pgfpatharc{180}{270}{4\arrowsize} + \pgfusepathqstroke + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharc{90}{180}{4\arrowsize} + \pgfusepathqstroke +} + + +\subsection{Declaring a Derived Arrow Tip Kind} + +It is possible to declare arrow kinds in terms of existing ones. For +these command to work correctly, the left and right extends must be +set correctly. + +\begin{command}{\pgfarrowsdeclarealias\marg{start name}\marg{end + name}\marg{old start name}\marg{old end name}} + This command can be used to create an alias (another name) for an + existing arrow kind. + +\begin{codeexample}[] +\pgfarrowsdeclarealias{<}{>}{arcs''}{arcs''}% +\begin{tikzpicture} + \pgfsetarrows{<->} + \pgfsetlinewidth{1ex} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} + \pgfusepath{stroke} + \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfarrowsdeclarereversed\marg{start name}\marg{end + name}\marg{old start name}\marg{old end name}} + This command creates a new arrow kind that is the ``reverse'' of an + existing arrow kind. The (automatically cerated) code of the new + arrow kind will contain a flip of the canvas and the meanings of the + left and right extend will be reversed. + +\begin{codeexample}[] +\pgfarrowsdeclarereversed{arcs reversed}{arcs reversed}{arcs''}{arcs''}% +\begin{tikzpicture} + \pgfsetarrows{arcs reversed-arcs reversed} + \pgfsetlinewidth{1ex} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} + \pgfusepath{stroke} + \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); +\end{tikzpicture} +\end{codeexample} +\end{command} + + + +\begin{command}{\pgfarrowsdeclarecombine\opt{|*|}\opt{\oarg{offset}}\marg{start + name}\marg{end name}\marg{first start name}\marg{first end + name}\penalty0\marg{second start name}\marg{second end name}} + This command creates a new arrow kind that combines two existing + arrow kinds. The first arrow kind is the ``innermost'' arrow kind, + the second arrow kind is the ``outermost.'' + + The code for the combined arrow kind will install a canvas + translation before the innermost arrow kind in drawn. This + translation is calculated such that the right tip of the innermost + arrow touches the right end of the outermost arrow. The optional + \meta{offset} can be used to increase (or decrease) the distance + between the inner and outermost arrow. + +\begin{codeexample}[] +\pgfarrowsdeclarecombine[\pgflinewidth] + {combined}{combined}{arcs''}{arcs''}{latex}{latex}% +\begin{tikzpicture} + \pgfsetarrows{combined-combined} + \pgfsetlinewidth{1ex} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} + \pgfusepath{stroke} + \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); +\end{tikzpicture} +\end{codeexample} + + In the star variant, the end of the line is not in the outermost + arrow, but inside the innermost arrow. + +\begin{codeexample}[] +\pgfarrowsdeclarecombine*[\pgflinewidth] + {combined'}{combined'}{arcs''}{arcs''}{latex}{latex}% +\begin{tikzpicture} + \pgfsetarrows{combined'-combined'} + \pgfsetlinewidth{1ex} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} + \pgfusepath{stroke} + \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfarrowsdeclaredouble\opt{\oarg{offset}}\marg{start + name}\marg{end name}\marg{old start name}\marg{old end + name}} + This command is a shortcut for combining an arrow kind with itself. + +\begin{codeexample}[] +\pgfarrowsdeclaredouble{<<}{>>}{arcs''}{arcs''}% +\begin{tikzpicture} + \pgfsetarrows{<<->>} + \pgfsetlinewidth{1ex} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} + \pgfusepath{stroke} + \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfarrowsdeclaretriple\opt{\oarg{offset}}\marg{start + name}\marg{end name}\marg{old start name}\marg{old end + name}} + This command is a shortcut for combining an arrow kind with itself + and then again. + +\begin{codeexample}[] +\pgfarrowsdeclaretriple{<<<}{>>>}{arcs''}{arcs''}% +\begin{tikzpicture} + \pgfsetarrows{<<<->>>} + \pgfsetlinewidth{1ex} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} + \pgfusepath{stroke} + \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); +\end{tikzpicture} +\end{codeexample} +\end{command} + + + + + +\subsection{Using an Arrow Tip Kind} + +The following commands install the arrow kind that will be used when +stroking is done. + +\begin{command}{\pgfsetarrowsstart\marg{start arrow kind}} + Installs the given \meta{start arrow kind} for all subsequent + strokes in the in the current \TeX-group. If \meta{start arrow kind} + is empty, no arrow tips will be drawn at the start of the last + segment of paths. +\begin{codeexample}[] +\begin{tikzpicture} + \pgfsetarrowsstart{latex} + \pgfsetlinewidth{1ex} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} + \pgfusepath{stroke} + \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetarrowsend\marg{start arrow kind}} + Like |\pgfsetarrowsstart|, only for the end of the arrow. +\begin{codeexample}[] +\begin{tikzpicture} + \pgfsetarrowsend{latex} + \pgfsetlinewidth{1ex} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} + \pgfusepath{stroke} + \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); +\end{tikzpicture} +\end{codeexample} +\end{command} + +\emph{Warning:} If the compatibility mode is active (which is the +default), there also exist old commands called |\pgfsetstartarrow| and +|\pgfsetendarrow|, which are incompatible with the meta-arrow +management. + + +\begin{command}{\pgfsetarrows\texttt{\char`\{}\meta{start kind}|-|\meta{end kind}\texttt{\char`\}}} + Calls |\pgfsetarrowsstart| for \meta{start kind} and + |\pgfsetarrowsend| for \meta{end kind}. +\begin{codeexample}[] +\begin{tikzpicture} + \pgfsetarrows{latex-to} + \pgfsetlinewidth{1ex} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} + \pgfusepath{stroke} + \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\subsection{Predefined Arrow Tip Kinds} + +\label{standard-arrows} + +The following arrow tip kinds are always defined: + +{ +\bigskip +\catcode`\|=12 +\begin{tabular}{ll} + \sarrow{stealth}{stealth} \\ + \sarrow{stealth reversed}{stealth reversed} \\ + \sarrow{to}{to} \\ + \sarrow{to reversed}{to reversed} \\ + \sarrow{latex}{latex} \\ + \sarrow{latex reversed}{latex reversed} \\ + \index{*vbar@\protect\texttt{\protect\myvbar} arrow tip}% + \index{Arrow tips!*vbar@\protect\texttt{\protect\myvbar}} + \texttt{|-|}& yields thick + \begin{tikzpicture}[arrows={|-|},thick] + \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \draw (0,0) -- (1,0); + \end{tikzpicture} and thin + \begin{tikzpicture}[arrows={|-|},thin] + \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \draw (0,0) -- (1,0); + \end{tikzpicture} +\end{tabular} +} + +For further arrow tips, see page~\pageref{section-library-arrows}. + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex new file mode 100644 index 00000000000..1318c780235 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex @@ -0,0 +1,183 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Design Principles} + +This section describes the basic layer of \pgfname. This layer is +build on top of the system layer. Whereas the system layer just +provides the absolute minimum for drawing graphics, the basic +layer provides numerous commands that make it possible to create +sophisticated graphics easily and also quickly. + +The basic layer does not provide a convenient syntax for describing +graphics, which is left to frontends like \tikzname. For this reason, the +basic layer is typically used only by ``other programs.'' For example, +the \textsc{beamer} package uses the basic layer extensively, but does +not need a convenient input syntax. Rather, speed and flexibility are +needed when \textsc{beamer} creates graphics. + +The following basic design principles underlie the basic layer: +\begin{enumerate} +\item Structuring into a core and several optional packages. +\item Consistently named \TeX\ macros for all graphics commands. +\item Path-centered description of graphics. +\item Coordinate transformation system. +\end{enumerate} + + + +\subsection{Core and Optional Packages} + +The basic layer consists of a \emph{core package}, called |pgfcore|, +which provides the most basic commands, and several optional package +like |pgfbaseshade| that offer more special-purpose commands. + +You can include the core by saying |\usepackage{pgfcore}| or, as a +plain \TeX\ user, |\input pgfcore.tex|. + +The following optional packages are provided by the basic layer: +\begin{itemize} +\item + |pgfbaseplot| provides commands for plotting functions. +\item + |pgfbaseshapes| provides commands for drawing shapes and + nodes. +\item + |pgfbaseimage| provides commands for including external + images. The |graphicx| package does a much better job at this than + the |pgfbaseimage| package does, so you should normally use + |\includegraphics| and not |\pgfimage|. However, in some situations + (like when masking is needed or when plain \TeX\ is used) this + package is needed. +\item + |pgfbaselayers| provides commands for creating layered + graphics. Using layers you can later on say that a certain path + should be behind a path that was specified earlier. +\item + |pgfbasesnakes| provides commands for adding snaked lines to the + path. Such lines are not straight but rather wind in some specific + fashion. +\end{itemize} + +If you say |\usepackage{pgf}| or |\input pgf.tex|, all of the optional +packages are loaded (as well as the core and the system layer). + + +\subsection{Communicating with the Basic Layer via Macros} + +In order to ``communicate'' with the basic layer you use long +sequences of commands that start with |\pgf|. You are only allowed to +give these commands inside a |{pgfpicture}| environment. (Note that +|{tikzpicture}| opens a |{pgfpicture}| internally, so you can freely +mix \pgfname\ commands and \tikzname\ commands inside a +|{tikzpicture}|.) It is possible to ``do other things'' between the +commands. For example, you might use one command to move to a certain +point, then have a complicated computation of the next point, and then +move there. + +\begin{codeexample}[] +\newdimen\myypos +\begin{pgfpicture} + \pgfpathmoveto{\pgfpoint{0cm}{\myypos}} + \pgfpathlineto{\pgfpoint{1cm}{\myypos}} + \advance \myypos by 1cm + \pgfpathlineto{\pgfpoint{1cm}{\myypos}} + \pgfpathclose + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + +The following naming conventions are used in the basic layer: + +\begin{enumerate} +\item + All commands and environments start with |pgf|. +\item + All commands that specify a point (a coordinate) start with |\pgfpoint|. +\item + All commands that extend the current path start with |\pgfpath|. +\item + All commands that set/change a graphics parameter start with |\pgfset|. +\item + All commands that use a previously declared object (like a path, + image or shading) start with |\pgfuse|. +\item + All commands having to do with coordinate transformations start with + |\pgftransform|. +\item + All commands having to do with arrow tips start with |\pgfarrows|. +\item + All commands for ``quickly'' extending or drawing a path start with + |\pgfpathq| or |\pgfusepathq|. +\end{enumerate} + + +\subsection{Path-Centered Approach} + +In \pgfname\ the most important entity is the \emph{path}. All +graphics are composed of numerous paths that can be stroked, +filled, shaded, or clipped against. Paths can be closed or open, they +can self-intersect and consist of unconnected parts. + +Paths are first \emph{constructed} and then \emph{used}. In order to +construct a path, you can use commands starting with |\pgfpath|. Each +time such a command is called, the current path is extended in some +way. + +Once a path has been completely constructed, you can use it using the +command |\pgfusepath|. Depending on the parameters given to this +command, the path will be stroked (drawn) or filled or subsequent +drawings will be clipped against this path. + + + + +\subsection{Coordinate Versus Canvas Transformations} + +\label{section-design-transformations} + +\pgfname\ provides two transformation systems: \pgfname's own +\emph{coordinate} transformation matrix and \pdf's or PostScript's +\emph{canvas} transformation matrix. These two systems are quite +different. Whereas a scaling by a factor of, say, $2$ of the canvas +causes \emph{everything} to be scaled by this factor (including +the thickness of lines and text), a scaling of two in the coordinate +system causes only the \emph{coordinates} to be scaled, but not the +line width nor text. + +By default, all transformations only apply to the coordinate +transformation system. However, using the command |\pgflowlevel| +it is possible to apply a transformation to the canvas. + +Coordinate transformations are often preferable over canvas +transformations. Text and lines that are transformed using canvas +transformations suffer from differing sizes and lines whose thickness +differs depending on whether the line is horizontal or vertical. To +appreciate the difference, consider the following two ``circles'' both +of which have been scaled in the $x$-direction by a factor of $3$ and +by a factor of $0.5$ in the $y$-direction. The left circle uses a +canvas transformation, the right uses \pgfname's coordinate +transformation (some viewers will render the left graphic incorrectly +since they do no apply the low-level transformation the way they +should): + +\begin{tikzpicture}[line width=5pt] + \useasboundingbox (-1.75,-1) rectangle (14,1); + + \begin{scope} + \pgflowlevel{\pgftransformxscale{3}} + \pgflowlevel{\pgftransformyscale{.5}} + + \draw (0,0) circle (0.5cm); + \draw (.55cm,0pt) node[right] {canvas}; + \end{scope} + \begin{scope}[xshift=9cm,xscale=3,yscale=.5] + \draw (0,0) circle (0.5cm); + \draw (.55cm,0pt) node[right] {coordinate}; + \end{scope} +\end{tikzpicture} + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex new file mode 100644 index 00000000000..ebadb54e5ff --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex @@ -0,0 +1,278 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Declaring and Using Images} +\label{section-images} + + +This section describes the |pgfbaseimage| package. + +\begin{package}{pgfbaseimage} + This package offers an abstraction of the image inclusion + process. It is loaded automatically by |pgf|, but you can load it + manually if you have only included |pgfcore|. +\end{package} + +\subsection{Overview} + +To be quite frank, \LaTeX's |\includegraphics| is designed better than +|pgfbaseimage|. For this reason, \emph{I recommend that you use the + standard image inclusion mechanism of your format}. Thus, \LaTeX\ +users are encouraged to use |\includegraphics| to include images. + +However, there are reasons why you might need to use the image +inclusion facilities of \pgfname: +\begin{itemize} +\item + There is no standard image inclusion mechanism in your format. For + example, plain \TeX\ does not have one, so \pgfname's inclusion + mechanism is ``better than nothing.'' + + However, this applies only to the |pdftex| backend. For all other + backends, \pgfname\ currently maps its commands back to the |graphicx| + package. Thus, in plain \TeX, this does not really help. It might be + a good idea to fix this in the future such that \pgfname\ becomes + independent of \LaTeX, thereby providing a uniform image abstraction + for all formats. +\item + You wish to use masking. This is a feature that is only supported by + \pgfname, though I hope that someone will implement this also for + the graphics package in \LaTeX\ in the future. +\end{itemize} + +Whatever your choice, you can still use the usual image inclusion +facilities of the |graphics| package. + +The general approach taken by \pgfname\ to including an image is the +following: First, |\pgfdeclareimage| declares the +image. This must be done prior to the first use of the image. Once you +have declared an image, you can insert it into the text using +|\pgfuseimage|. The advantage of this two-phase approach is that, at +least for \textsc{pdf}, the image data will only be included once in the +file. This can drastically reduce the file size if you use an image +repeatedly, for example in an overlay. However, there is also a +command called |\pgfimage| that declares and then immediately uses the +image. + +To speedup the compilation, you may wish to use the following class +option: +\begin{packageoption}{draft} + In draft mode boxes showing the image name replace the + images. It is checked whether the image files exist, but they are + not read. If either height or width is not given, 1cm is used + instead. +\end{packageoption} + +\subsection{Declaring an Image} + +\begin{command}{\pgfdeclareimage\oarg{options}\marg{image + name}\marg{filename}} + Declares an image, but does not paint anything. To draw the image, + use |\pgfuseimage{|\meta{image name}|}|. The \meta{filename} may not + have an extension. For \textsc{pdf}, the extensions |.pdf|, |.jpg|, + and |.png| will automatically tried. For PostScript, the extensions + |.eps|, |.epsi|, and |.ps| will be tried. + + The following options are possible: + \begin{itemize} + \item + \declare{|height=|\meta{dimension}} sets the height of the + image. If the width is not specified simultaneously, the aspect + ratio of the image is kept. + \item + \declare{|width=|\meta{dimension}} sets the width of the + image. If the height is not specified simultaneously, the aspect + ratio of the image is kept. + \item + \declare{|page=|\meta{page number}} selects a given page number + from a multipage document. Specifying this option will have the + following effect: first, \pgfname\ tries to find a file named + \begin{quote} + \meta{filename}|.page|\meta{page number}|.|\meta{extension} + \end{quote} + If such a file is found, it will be used instead of the originally + specified filename. If not, \pgfname\ inserts the image stored in + \meta{filename}|.|\meta{extension} and if a recent version of + |pdflatex| is used, only the selected page is inserted. For older + versions of |pdflatex| and for |dvips| the complete document is + inserted and a warning is printed. + \item + \declare{|interpolate=|\meta{true or false}} selects whether the + image should ``smoothed'' when zoomed. False by default. + \item + \declare{|mask=|\meta{mask name}} selects a transparency mask. The + mask must previously be declared using |\pgfdeclaremask| (see + below). This option only has an effect for |pdf|. Not all viewers + support masking. + \end{itemize} + +\begin{codeexample}[code only] +\pgfdeclareimage[interpolate=true,height=1cm]{image1}{pgf-tu-logo} +\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]{image2}{pgf-tu-logo} +\pgfdeclareimage[interpolate=true,height=1cm]{image3}{pgf-tu-logo} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfaliasimage\marg{new image name}\marg{existing image name}} + The \marg{existing image name} is ``cloned'' and the \marg{new image + name} can now be used whenever original image is used. This + command is useful for creating aliases for alternate extensions + and for accessing the last image inserted using |\pgfimage|. + + \example |\pgfaliasimage{image.!30!white}{image.!25!white}| +\end{command} + + +\subsection{Using an Image} + +\begin{command}{\pgfuseimage\marg{image name}} + Inserts a previously declared image into the \emph{normal text}. If + you wish to use it in a |{pgfpicture}| environment, you must put a + |\pgftext| around it. + + If the macro |\pgfalternateextension| expands to some nonempty + \meta{alternate extension}, \pgfname\ will first try to use the image + names \meta{image name}|.|\meta{alternate extension}. If this + image is not defined, \pgfname\ will next check whether \meta{alternate + extension} contains a |!| character. If so, everything up to this + exclamation mark and including it is deleted from \meta{alternate + extension} and the \pgfname\ again tries to use the image \meta{image + name}|.|\meta{alternate extension}. This is repeated until + \meta{alternate extension} no longer contains a~|!|. Then the + original image is used. + + The |xxcolor| package sets the alternate extension to the current + color mixin. + +\begin{codeexample}[] +\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]{image1}{pgf-tu-logo} +\pgfdeclareimage[interpolate=true,width=1cm]{image2}{pgf-tu-logo} +\pgfdeclareimage[interpolate=true,height=1cm]{image3}{pgf-tu-logo} +\begin{pgfpicture} + \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}} + \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}} + \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}} + + \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + + The following example demonstrates the effect of using + |\pgfuseimage| inside a color mixin environment. + +\begin{codeexample}[] +\pgfdeclareimage[interpolate=true,width=1cm,height=1cm] + {image1.!25!white}{pgf-tu-logo.25} +\pgfdeclareimage[interpolate=true,width=1cm] + {image2.25!white}{pgf-tu-logo.25} +\pgfdeclareimage[interpolate=true,height=1cm] + {image3.white}{pgf-tu-logo.25} +\begin{colormixin}{25!white} +\begin{pgfpicture} + \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}} + \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}} + \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}} + + \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{colormixin} +\end{codeexample} +\end{command} + +\begin{command}{\pgfalternateextension} + You should redefine this command to install a different alternate + extension. + + \example |\def\pgfalternateextension{!25!white}| +\end{command} + + +\begin{command}{\pgfimage\oarg{options}\marg{filename}} + Declares the image under the name |pgflastimage| and + immediately uses it. You can ``save'' the image for later usage by + invoking |\pgfaliasimage| on |pgflastimage|. + +\begin{codeexample}[] +\begin{colormixin}{25!white} +\begin{pgfpicture} + \pgftext[at=\pgfpoint{1cm}{5cm},left,base] + {\pgfimage[interpolate=true,width=1cm,height=1cm]{pgf-tu-logo}} + \pgftext[at=\pgfpoint{1cm}{3cm},left,base] + {\pgfimage[interpolate=true,width=1cm]{pgf-tu-logo}} + \pgftext[at=\pgfpoint{1cm}{1cm},left,base] + {\pgfimage[interpolate=true,height=1cm]{pgf-tu-logo}} + + \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{colormixin} +\end{codeexample} +\end{command} + + + +\subsection{Masking an Image} + + +\begin{command}{\pgfdeclaremask\oarg{options}\marg{mask name}\marg{filename}} + Declares a transparency mask named \meta{mask name} (called a + \emph{soft mask} in the \textsc{pdf} specification). This mask is + read from the file \meta{filename}. This file should contain a + grayscale image that is as large as the actual image. A white + pixel in the mask will correspond to ``transparent,'' a black pixel + to ``solid,'' and gray values correspond to intermediate values. The + mask must have a single ``color channel.'' This means that the + mask must be a ``real'' grayscale image, not an \textsc{rgb}-image + in which all \textsc{rgb}-triples happen to have the same + components. + + You can only mask images the are in a ``pixel format.'' These are + |.jpg| and |.png|. You cannot mask |.pdf| images in this way. Also, + again, the mask file and the image file must have the same size. + + The following options may be given: + \begin{itemize} + \item |matte=|\marg{color components} sets the so-called + \emph{matte} of the actual image (strangely, this has to be + specified together with the mask, not with the image itself). The + matte is the color that has been used to preblend the image. For + example, if the image has been preblended with a red background, + then \meta{color components} should be set to |{1 0 0}|. The + default is |{1 1 1}|, which is white in the rgb model. + + The matte is specified in terms of the parent's image color + space. Thus, if the parent is a grayscale image, the matte has to + be set to |{1}|. + \end{itemize} + \example +\begin{codeexample}[] +%% Draw a large colorful background +\pgfdeclarehorizontalshading{colorful}{5cm}{color(0cm)=(red); +color(2cm)=(green); color(4cm)=(blue); color(6cm)=(red); +color(8cm)=(green); color(10cm)=(blue); color(12cm)=(red); +color(14cm)=(green)} +\hbox{\pgfuseshading{colorful}\hskip-14cm\hskip1cm +\pgfimage[height=4cm]{pgf-apple}\hskip1cm +\pgfimage[height=4cm]{pgf-apple.mask}\hskip1cm +\pgfdeclaremask{mymask}{pgf-apple.mask} +\pgfimage[mask=mymask,height=4cm,interpolate=true]{pgf-apple}} +\end{codeexample} +\end{command} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex new file mode 100644 index 00000000000..db8136e87de --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex @@ -0,0 +1,142 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Layered Graphics} + +\label{section-layers} + +\begin{package}{pgfbaselayers} + This package provides a commands and environments for composing a + picture from multiple layers. The package is loaded automatically by + |pgf|, but you can load it manually if you have only included + |pgfcore|. +\end{package} + + + +\subsection{Overview} + +\pgfname\ provides a layering mechanism for composing graphics from +multiple layers. (This mechanism is not be confused with the +conceptual ``software layers'' the \pgfname\ system is composed of.) +Layers are often used in graphic programs. The idea is that you can +draw on the different layers in any order. So you might start drawing +something on the ``background'' layer, then something on the +``foreground'' layer, then something on the ``middle'' layer, and then +something on the background layer once more, and so on. At the end, no +matter in which ordering you drew on the different layers, the layers +are ``stacked on top of each other'' in a fixed ordering to produce +the final picture. Thus, anything drawn on the middle layer would come +on top of everything of the background layer. + +Normally, you do not need to use different layers since you will have +little trouble ``ordering'' your graphic commands in such a way that +layers are superfluous. However, in certain situations you only +``know'' what you should draw behind something else after the +``something else'' has been drawn. + +For example, suppose you wish to draw a yellow background behind your +picture. The background should be as large as the bounding box of the +picture, plus a little border. If you know the size of the bounding box +of the picture at its beginning, this is easy to accomplish. However, +in general this is not the case and you need to create a +``background'' layer in addition to the standard ``main'' layer. Then, +at the end of the picture, when the bounding box has been established, +you can add a rectangle of the appropriate size to the picture. + + + +\subsection{Declaring Layers} + +In \pgfname\ layers are referenced using names. The standard layer, +which is a bit special in certain ways, is called |main|. If nothing +else is specified, all graphic commands are added to the |main| +layer. You can declare a new layer using the following command: + +\begin{command}{\pgfdeclarelayer\marg{name}} + This command declares a layer named \meta{name} for later + use. Mainly, this will setup some internal bookkeeping. +\end{command} + +The next step toward using a layer is to tell \pgfname\ which layers +will be part of the actual picture and which will be their +ordering. Thus, it is possible to have more layers declared than are +actually used. + +\begin{command}{\pgfsetlayers\marg{layer list}} + This command, which should be used \emph{outside} a |{pgfpicture}| + environment, tells \pgfname\ which layers will be used in + pictures. They are stacked on top of each other in the order + given. The layer |main| should always be part of the list. Here is + an example: +\begin{codeexample}[code only] +\pgfdeclarelayer{background} +\pgfdeclarelayer{foreground} +\pgfsetlayers{background,main,foreground} +\end{codeexample} +\end{command} + + +\subsection{Using Layers} + +Once the layers of your picture have been declared, you can start to +``fill'' them. As said before, all graphics commands are normally +added to the |main| layer. Using the |{pgfonlayer}| environment, you +can tell \pgfname\ that certain commands should, instead, be added to +the given layer. + +\begin{environment}{{pgfonlayer}\marg{layer name}} + The whole \meta{environment contents} is added to the layer with the + name \meta{layer name}. This environment can be used anywhere inside + a picture. Thus, even if it is used inside a |{pgfscope}| or a \TeX\ + group, the contents will still be added to the ``whole'' picture. + Using this environment multiple times inside the same picture will + cause the \meta{environment contents} to accumulate. + + \emph{Note:} You can \emph{not} add anything to the |main| layer + using this environment. The only way to add anything to the main + layer is to give graphic commands outside all |{pgfonlayer}| + environments. + +\begin{codeexample}[] +\pgfdeclarelayer{background layer} +\pgfdeclarelayer{foreground layer} +\pgfsetlayers{background layer,main,foreground layer} +\begin{tikzpicture} + % On main layer: + \fill[blue] (0,0) circle (1cm); + + \begin{pgfonlayer}{background layer} + \fill[yellow] (-1,-1) rectangle (1,1); + \end{pgfonlayer} + + \begin{pgfonlayer}{foreground layer} + \node[white] {foreground}; + \end{pgfonlayer} + + \begin{pgfonlayer}{background layer} + \fill[black] (-.8,-.8) rectangle (.8,.8); + \end{pgfonlayer} + + % On main layer again: + \fill[blue!50] (-.5,-1) rectangle (.5,1); +\end{tikzpicture} +\end{codeexample} +\end{environment} + +\begin{plainenvironment}{{pgfonlayer}\marg{layer name}} + This is the plain \TeX\ version of the environment. +\end{plainenvironment} + + + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex new file mode 100644 index 00000000000..c2231219113 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex @@ -0,0 +1,987 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Nodes and Shapes} + +\label{section-shapes} + +This section describes the |pgfbaseshapes| package. + +\begin{package}{pgfbaseshapes} + This package defines commands both for creating nodes and for + creating shapes. The package is loaded automatically by |pgf|, but + you can load it manually if you have only included |pgfcore|. +\end{package} + + +\subsection{Overview} + +\pgfname\ comes with a sophisticated set of commands for creating +\emph{nodes} and \emph{shapes}. A \emph{node} is a graphical object +that consists (typically) of (one or more) text labels and some +additional stroked or filled paths. Each node has a certain +\emph{shape}, which may be something simple like a |rectangle| or a +|circle|, but it may also be something complicated like a +|uml class diagram| (this shape is currently not implemented, +though). Different nodes that have the same shape may look quite +different, however, since shapes (need not) specify whether the shape +path is stroked or filled. + + +\subsubsection{Creating and Referencing Nodes} + +You create a node by calling the macro |\pgfnode| or the more general +|\pgfmultipartnode|. These macro takes several parameters and draws +the requested shape at a certain position. In addition, it will +``remember'' the node's position within the current +|{pgfpicture}|. You can then, later on, refer to the +node's position. Coordinate transformations are ``fully supported,'' +which means that if you used coordinate transformations to shift or +rotate the shape of a node, the node's position will still be correctly +determined by \pgfname. This is \emph{not} the case if you use canvas +transformations, instead. + + +\subsubsection{Anchors} + +An important property of a node or a shape in general are its +\emph{anchors}. Anchors are ``important'' positions in a shape. For +example, the |center| anchor lies at the center of a shape, the +|north| anchor is usually ``at the top, in the middle'' of a shape, +the |text| anchor is the lower left corner of the shape's text label +(if present), and so on. + +Anchors are important both when you create a node and when you +reference it. When you create a node, you specify the node's +``position'' by asking \pgfname\ to place the shape in such a way that +a certain anchor lies at a certain point. For example, you might ask +that the node is placed such that the |north| anchor is at the +origin. This will effectively cause the node to be placed below the +origin. + +When you reference a node, you always reference an anchor of the +node. For example, when you request the ``|north| anchor of the node +just placed'' you will get the origin. However, you can also request +the ``|south| anchor of this node,'' which will give you a point +somewhere below the origin. When a coordinate transformation was in +force at the time of creation of a node, all anchors are also +transformed accordingly. + +\subsubsection{Layers of a Shape} + +The simplest shape, the |coordinate|, has just one anchor, namely the +|center|, and a label (which is usually empty). More complicated +shapes like the |rectangle| shape also have a \emph{background + path}. This is a \pgfname-path that is defined by the shape. The +shape does not prescribe what should happen with the path: When a node +is created this path may be stroked (resulting in a frame around the +label), filled (resulting in a background color for the text), or just +discarded. + +Although most shapes consist just of a background path plus some label +text, when a shape is drawn, up to seven different layers are drawn: + +\begin{enumerate} +\item + The ``behind the background layer.'' Unlike the background path, + which be used in different ways by different nodes, the graphic + commands given for this layer will always stroke or + always fill the path they construct. They might also insert some + text that is ``behind everything.'' +\item + The background path layer. How this path is used depends on how the + arguments of the |\pgfnode| command. +\item + The ``before the background path layer.'' This layer works like the + first one, only the commands of this layer are executed after the + background path has been used (in whatever way the creator of the + node chose). +\item + The label layer. This layer inserts the node's text box(es). +\item + The ``behind the foreground layer.'' This layer, like the + first layer, once more contains graphic commands that are ``simply + executed.'' +\item + The foreground path layer. This path is treated in the same way as the + background path, only it is drawn only after the label text has been + drawn. +\item + The ``before the foreground layer.'' +\end{enumerate} + +Which of these layers are actually used depends on the shape. + + + +\subsubsection{Node Parts} + +A shape typically does not consist only of different background and +foreground paths, but it may also have text labels. Indeed, for many +shapes the text labels are the more important part of the shape. + +Most shapes will have only one text label. In this case, this text +label is simply passed as a parameter to the |\pgfnode| command. When +the node is drawn, the text label is shifted around such that its +lower left corner is at the |text| anchor of the node. + +More complicated shapes may have more than one text label. Nodes of +such shapes are called \emph{multipart nodes}. The different +\emph{node parts} are simply the different text labels. For example, a +|uml class| shape might have a |class name| part, a |method| part and +an |attributes| part. Indeed, single part nodes are a special case of +multipart nodes: They only have one part named |text|. + +When a shape is declared, you must specify the node parts. There is a +simple command called |\nodeparts| that takes a list of the part names +as input. When you create a node of a multipart shape, for each part +of the node you must have setup a \TeX-box containing the text of the +part. For a part named |XYZ| you must setup the box +|\pgfnodepartXYZbox|. The box will be placed at the anchor |XYZ|. See +the description of |\pgfmultipartnode| for more details. + + +\subsection{Creating Nodes} + +You create a node using on of the following commands: + +\begin{command}{\pgfnode\marg{shape}\marg{anchor}\marg{label + text}\marg{name}\marg{path usage command}} + This command creates a new node. The \meta{shape} of the node must + have been declared previously using |\pgfdeclareshape|. + + The shape is shifted such that the \meta{anchor} is at the + origin. In order to place the shape somewhere else, use the + coordinate transformation prior to calling this command. + + The \meta{name} is a name for later reference. If no name is given, + nothing will be ``saved'' for the node, it will just be drawn. + + The \meta{path usage command} is executed for the background and the + foreground path (if the shape defines them). + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (4,3); + { + \pgftransformshift{\pgfpoint{1cm}{1cm}} + \pgfnode{rectangle}{north}{Hello World}{hellonode}{\pgfusepath{stroke}} + } + { + \color{red!20} + \pgftransformrotate{10} + \pgftransformshift{\pgfpoint{3cm}{1cm}} + \pgfnode{rectangle}{center} + {\color{black}Hello World}{hellonode}{\pgfusepath{fill}} + } +\end{tikzpicture} +\end{codeexample} + + As can be seen, all coordinate transformations are also applied to + the text of the shape. Sometimes, it is desirable that the + transformations are applied to the point where the shape will be + anchored, but you do not wish the shape itself to the + transformed. In this case, you should call + |\pgftransformresetnontranslations| prior to calling the |\pgfnode| + command. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (4,3); + { + \color{red!20} + \pgftransformrotate{10} + \pgftransformshift{\pgfpoint{3cm}{1cm}} + \pgftransformresetnontranslations + \pgfnode{rectangle}{center} + {\color{black}Hello World}{hellonode}{\pgfusepath{fill}} + } +\end{tikzpicture} +\end{codeexample} + + The \meta{label text} is typeset inside the \TeX-box + |\pgfnodeparttextbox|. This box is shown at the |text| anchor of the + node, if the node has a |text| part. See the description of + |\pgfmultipartnode| for details. +\end{command} + +\begin{command}{\pgfmultipartnode\marg{shape}\marg{anchor}\marg{name}\marg{path + usage command}} + This command is the more general (and less user-friendly) version of + the |\pgfnode| command. While the |\pgfnode| command can only be + used for shapes that have a single part (which is the case for most + shapes), this command can also be used with multi-part nodes. + + When this command is called, for each node part of the node you must + have setup one \TeX-box. Suppose the shape has two parts: The |text| + part and the |output| part. Then, prior to calling + |\pgfmultipartnode|, you must have setup the boxes + |\pgfnodeparttextbox| and |\pgfnodepartoutputbox|. These boxes may + contain any \TeX-text. The shape code will then compute the + positions of the shape's anchors based on the sizes of the these + shapes. Finally, when the node is drawn, the boxes are placed at the + anchor positions |text| and |output|. + +\begin{codeexample}[] +\setbox\pgfnodeparttextbox=\hbox{$q_1$} +\setbox\pgfnodepartoutputbox=\hbox{01} +\begin{pgfpicture} + \pgfmultipartnode{state with output}{center}{my state}{\pgfusepath{stroke}} +\end{pgfpicture} +\end{codeexample} + + \emph{Note:\/} Be careful when using the |\setbox| command inside a + |{pgfpicture}| command. You will have to use |\pgfinterruptpath| at + the beginning of the box and |\endpgfinterruptpath| at the end of + the box to make sure that the box is typeset correctly. In the above + example this problem was sidestepped by moving the box construction + outside the environment. + + \emph{Note:\/} It is not necessary to use |\newbox| for every node + part name. Although you need a different box for each part of a + single shape, two different shapes may very well use the same box + even when the names of the parts are different. Suppose you have a + |state with output| shape that has an |output| part and you have a + |uml class| shape that has a |methods| part. Then, in order to avoid + exhausting \TeX's limited number of box registers, you can say +\begin{codeexample}[code only] +\newbox\pgfnodepartoutputbox +\let\pgfnodepartmethodsbox=\pgfnodepartoutputbox +\end{codeexample} + Also, when you have a node part name with spaces like |class name|, + it may be useful to create an alias: +\begin{codeexample}[code only] +\newbox\mybox +\expandafter\let\csname pgfnodepartclass namebox\endcsname=\mybox +\end{codeexample} +\end{command} + +There are a number of values that have an influence on the size of a +node. These parameters can be changed using the following commands: + +\begin{command}{\pgfsetshapeminwidth\marg{dimension}} + This command sets the macro \declare{|\pgfshapeminwidth|} to + \meta{dimension}. This dimension is the \emph{recommended} minimum + width of a shape. Thus, when a shape is drawn and when the shape's + width would be smaller than \meta{dimension}, the shape's width is + enlarged by adding some empty space. + + Note that this value is just a recommendation. A shape may choose to + ignore the value of |\pgfshapeminwidth|. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfsetshapeminwidth{3cm} + \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetshapeminheight\marg{dimension}} + Works like |\pgfsetshapeminwidth|. +\end{command} + + +\begin{command}{\pgfsetshapeinnerxsep\marg{dimension}} + This command sets the macro \declare{|\pgfshapeinnerxsep|} to + \meta{dimension}. This dimension is the \emph{recommended} horizontal + inner separation between the label text and the background path. As + before, this value is just a recommendation and a shape may choose + to ignore the value of |\pgfshapeinnerxsep|. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfsetshapeinnerxsep{1cm} + \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetshapeinnerysep\marg{dimension}} + Works like |\pgfsetshapeinnerysep|. +\end{command} + + + +\begin{command}{\pgfsetshapeouterxsep\marg{dimension}} + This command sets the macro \declare{|\pgfshapeouterxsep|} to + \meta{dimension}. This dimension is the recommended horizontal + outer separation between the background path and the ``outer + anchors.'' For example, if \meta{dimension} is |1cm| then the + |east| anchor will be 1cm to the right of the right border of the + background path. + + As before, this value is just a recommendation. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfsetshapeouterxsep{.5cm} + \pgfnode{rectangle}{center}{Hello World}{x}{\pgfusepath{stroke}} + + \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetshapeouterysep\marg{dimension}} + Works like |\pgfsetshapeouterysep|. +\end{command} + + +\subsection{Using Anchors} + +Each shape defines a set of anchors. We saw already that the anchors +are used when the shape is drawn: the shape is placed in such a way +that the given anchor is at the origin (which in turn is typically +translated somewhere else). + +One has to look up the set of anchors of each shape, there is no +``default'' set of anchors, except for the |center| anchor, which +should always be present. Also, most shapes will declare anchors like +|north| or |east|, but this is not guaranteed. + +Once a node has been defined, you can refer to its anchors using the +following commands: + +\begin{command}{\pgfpointanchor\marg{node}\marg{anchor}} + This command is another ``point command'' like the commands + described in Section~\ref{section-points}. It returns the coordinate + of the given \meta{anchor} in the given \meta{node}. The command can + be used in commands like |\pgfpathmoveto|. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + + \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} + + In the above example, you may have noticed something curious: The + rotation transformation is still in force when the anchors are + invoked, but it does not seem to have an effect. You might expect + that the rotation should apply to the already rotated points once + more. + + However, |\pgfpointanchor| returns a point that takes the current + transformation matrix into account: \emph{The inverse transformation + to the current coordinate transformation is applied to an anchor + point before returning it.} + + This behavior may seem a bit strange, but you will find it very + natural in most cases. If you really want to apply a transformation + to an anchor point (for example, to ``shift it away'' a little bit), + you have to invoke |\pgfpointanchor| without any transformations in + force. Here is an example: + +\makeatletter +\begin{codeexample}[] +\begin{pgfpicture} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + + { + \pgftransformreset + \pgfpointanchor{x}{east} + \xdef\mycoordinate{\noexpand\pgfpoint{\the\pgf@x}{\the\pgf@y}} + } + + \pgfpathcircle{\mycoordinate}{2pt} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpointshapeborder\marg{node}\marg{point}} + This command returns the point on the border of the shape that lies + on a straight line from the center of the node to \meta{point}. For + complex shapes it is not guaranteed that this point will actually + lie on the border, it may be on the border of a ``simplified'' + version of the shape. + +\begin{codeexample}[] +\begin{pgfpicture} + \begin{pgfscope} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + \end{pgfscope} + \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{2cm}{1cm}}}{2pt} + \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt} + \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{-1cm}{1cm}}}{2pt} + \pgfpathcircle{\pgfpoint{-1cm}{1cm}}{2pt} + \pgfusepath{fill} +\end{pgfpicture} +\end{codeexample} +\end{command} + + + +\subsection{Declaring New Shapes} + +Defining a shape is, unfortunately, a not-quite-trivial process. The +reason is that shapes need to be both very flexible (their size will +vary greatly according to circumstances) and they need to be +constructed reasonably ``fast.'' \pgfname\ must be able to handle +pictures with several hundreds of nodes and documents with thousands +of nodes in total. It would not do if \pgfname\ had to compute and +store, say, dozens of anchor positions for every node. + + +\subsubsection{What Must Be Defined For a Shape?} + +In order to define a new shape, you must provide: +\begin{itemize} +\item + a \emph{shape name}, +\item + code for computing the \emph{saved anchors} and \emph{saved + dimensions}, +\item + code for computing \emph{anchor} positions in terms of the saved anchors, +\item + optionally code for the \emph{background path} and \emph{foreground path}, +\item + optionally code for \emph{things to be drawn before or behind} the + background and foreground paths. +\item + optionally a list of node parts. +\end{itemize} + + +\subsubsection{Normal Anchors Versus Saved Anchors} + +Anchors are special places in shape. For example, the |north east| +anchor, which is a normal anchor, lies at the upper right corner of +the |rectangle| shape, as does |\northeast|, which is a saved +anchor. The difference is the following: \emph{saved anchors are + computed and stored for each node, anchors are only computed as + needed.} The user only has access to the normal anchors, but a +normal anchor can just ``copy'' or ``pass through'' the location of a +saved anchor. + +The idea behind all this is that a shape can declare a very large +number of normal anchors, but when a node of this shape is created, +these anchors are not actually computed. However, this causes a +problem: When we wish to reference an anchor of a node at some later +time, we must still able to compute the position of the anchor. For +this, we may need a lot of information: What was the transformation +matrix that was in force when the node was created? What was the size +of the text box? What were the values of the different separation +dimensions? And so on. + +To solve this problem, \pgfname\ will always compute the locations of +all \emph{saved anchors} and store these positions. Then, when an +normal anchor position is requested later on, the anchor position can +be given just from knowing where the locations of the saved anchors. + +As an example, consider the |rectangle| shape. For this shape two +anchors are saved: The |\northeast| corner and the |\southwest| +corner. A normal anchor like |north west| can now easily be expressed +in terms of these coordinates: Take the $x$-position of the +|\southwest| point and the $y$-position of the |\northeast| point. +The |rectangle| shape currently defines 13 normal anchors, but needs +only two saved anchors. Adding new anchors like a |south south east| +anchor would not increase the memory and computation requirements of +pictures. + +All anchors (both saved and normal) are specified in a local +\emph{shape coordinate space}. This is also true for the background +and foreground paths. The |\pgfnode| macro will automatically apply +appropriate transformations to the coordinates so that the shape is +shifted to the right anchor or otherwise transformed. + + +\subsubsection{Command for Declaring New Shapes} + +The following command declares a new shape: +\begin{command}{\pgfdeclareshape\marg{shape name}\marg{shape + specification}} + This command declares a new shape named \meta{shape name}. The shape + name can later be used in commands like |\pgfnode|. + + The \meta{shape specification} is some \TeX\ code containing calls + to special commands that are only defined inside the \meta{shape + specification} (similarly to commands like |\draw| that are only + available inside the |{tikzpicture}| environment). + + \example Here is the code of the |coordinate| shape: +\begin{codeexample}[code only] +\pgfdeclareshape{coordinate} +{ + \savedanchor\centerpoint{% + \pgf@x=.5\wd\pgfnodeparttextbox% + \pgf@y=.5\ht\pgfnodeparttextbox% + \advance\pgf@y by -.5\dp\pgfnodeparttextbox% + } + \anchor{center}{\centerpoint} + \anchorborder{\centerpoint} +} +\end{codeexample} + + The special commands are explained next. In the examples given for + the special commands a new shape will be constructed, which we might + call |simple rectangle|. It should behave like the normal rectangle + shape, only without bothering about the fine details like inner and + outer separations. The skeleton for the shape is the following. +\begin{codeexample}[code only] +\pgfdeclareshape{simple rectangle}{ + ... +} +\end{codeexample} + + \begin{command}{\nodeparts\marg{list of node parts}} + This command declares which parts make up nodes of this shape. A + \emph{node part} is a (possibly empty) text label that is drawn + when a node of the shape is created. + + By default, a shape has just one node part called |text|. However, + there can be several node parts. For example, the + |state with output| shape has two parts: the |text| part, which + shows that state's name, and an |output| part, which shows the + output produced when the state is reached. For the + |state with output| shape the |\nodeparts| command was called with + the argument |{text,output}|. + + When a multipart node is created, the text labels are drawn in the + sequences listed in the \meta{list of node parts}. For each node + part there you must have declared one anchor and the \TeX-box of + the part is placed at this anchor. For a node part called |XYZ| + the \TeX-box |\pgfnodepartXYZbox| is placed at anchor |XYZ|. + \end{command} + + \begin{command}{\savedanchor\marg{command}\marg{code}} + This command declares a saved anchor. The argument \meta{command} + should be a \TeX\ macro name like |\centerpoint|. + + The \meta{code} will be executed each time |\pgfnode| (or + |\pgfmultipartnode|) is called to create a node of the shape + \meta{shape name}. When the \meta{code} + is executed, the \TeX-boxes of the node parts will contain the + text labels of the node. Possibly, these box are void. For + example, if there is just a |text| part, the node + |\pgfnodeparttextbox| will be setup when the \meta{code} is + executed. + + The \meta{code} can use the width, height, and depth of the + box(es) to compute the location of the saved anchor. In addition, + the \meta{code} can take into account the values of dimensions like + |\pgfshapeminwidth| or |\pgfshapeinnerxsep|. Furthermore, the + \meta{code} can take into consideration the values of any further + shape-specific variables that are set at the moment when + |\pgfnode| is called. + + The net effect of the \meta{code} should be to set the two \TeX\ + dimensions |\pgf@x| and |\pgf@y|. One way to achieve this is to + say |\pgfpoint{|\meta{x value}|}{|\meta{y value}|}| at the end of + the \meta{code}, but you can also just set these variables. + The values that |\pgf@x| and |\pgf@y| have after the code has been + executed, let us call them $x$ and $y$, will be recorded and + stored together with the node that is created by the command + |\pgfnode|. + + The macro \meta{command} is defined to be + |\pgfpoint{|$x$|}{|$y$|}|. However, the \meta{command} is only + locally defined while anchor positions are being computed. Thus, + it is possible to use very simple names for \meta{command}, like + |\center| or |\a|, without causing a name-clash. (To be precise, + very simple \meta{command} names will clash with existing names, + but only locally inside the computation of anchor positions; and + we do not need the normal |\center| command during these + computations.) + + For our |simple rectangle| shape, we will need only one saved + anchor: The upper right corner. The lower left corner could either + be the origin or the ``mirrored'' upper right corner, depending on + whether we want the text label to have its lower left corner at + the origin or whether the text label should be centered on the + origin. Either will be fine, for the final shape this will make no + difference since the shape will be shifted anyway. So, let us + assume that the text label is centered on the origin (this will be + specified later on using the |text| anchor). We get + the following code for the upper right corner: +\begin{codeexample}[code only] +\savedanchor{\upperrightcorner}{ + \pgf@y=.5\ht\pgfnodeparttextbox % height of the box, ignoring the depth + \pgf@x=.5\wd\pgfnodeparttextbox % width of the box +} +\end{codeexample} + + If we wanted to take, say, the |\pgfshapeminwidth| into account, + we could use the following code: + +\begin{codeexample}[code only] +\savedanchor{\upperrightcorner}{ + \pgf@y=.\ht\pgfnodeparttextbox % height of the box + \pgf@x=.\wd\pgfnodeparttextbox % width of the box + \setlength{\pgf@xa}{\pgfshapeminwidth} + \ifdim\pgf@x<.5\pgf@xa + \pgf@x=.5\pgf@xa + \fi +} +\end{codeexample} + Note that we could not have written |.5\pgfshapeminwidth| since + the minium width is stored in a ``plain text macro,'' not as a + real dimension. So if |\pgfshapeminwidth| depth were + 2cm, writing |.5\pgfshapeminwidth| would yield the same as |.52cm|. + + In the ``real'' |rectangle| shape the code is somewhat more + complex, but you get the basic idea. + \end{command} + \begin{command}{\saveddimen\marg{command}\marg{code}} + This command is similar to |\savedanchor|, only instead of setting + \meta{command} to |\pgfpoint{|$x$|}{|$y$|}|, the \meta{command} is + set just to (the value of) $x$. + + In the |simple rectangle| shape we might use a saved dimension to + store the depth of the shape box. + +\begin{codeexample}[code only] +\shapedimen{\depth}{ + \pgf@x=\dp\pgfnodeparttextbox +} +\end{codeexample} + \end{command} + \begin{command}{\anchor\marg{name}\marg{code}} + This command declares an anchor named \meta{name}. Unlike for saved + anchors, the \meta{code} will not be executed each time a node is + declared. Rather, the \meta{code} is only executed when the anchor + is specifically requested; either for anchoring the node during + its creation or as a position in the shape referenced later on. + + The \meta{name} is a quite arbitrary string that is not ``passed + down'' to the system level. Thus, names like |south| or |1| or + |::| would all be fine. + + A saved anchor is not automatically also a normal anchor. If you + wish to give the users access to a saved anchor you must declare a + normal anchor that just returns the position of the saved anchor. + + When the \meta{code} is executed, all saved anchor macros will be + defined. Thus, you can reference them in your \meta{code}. The + effect of the \meta{code} should be to set the values of |\pgf@x| + and |\pgf@y| to the coordinates of the anchor. + + Let us consider some example for the |simple rectangle| + shape. First, we would like to make the upper right corner + publicly available, for example as |north east|: + +\begin{codeexample}[code only] +\anchor{north east}{\upperrightcorner} +\end{codeexample} + + The |\upperrightcorner| macro will set |\pgf@x| and |\pgf@y| to + the coordinates of the upper right corner. Thus, |\pgf@x| and + |\pgf@y| will have exactly the right values at the end of the + anchor's code. + + Next, let us define a |north west| anchor. For this anchor, we can + negate the |\pgf@x| variable: + +\begin{codeexample}[code only] +\anchor{north west}{ + \upperrightcorner + \pgf@x=-\pgf@x +} +\end{codeexample} + + Finally, it is a good idea to always define a |center| anchor, + which will be the default location for a shape. + +\begin{codeexample}[code only] +\anchor{center}{\pgfpointorigin} +\end{codeexample} + + You might wonder whether we should not take into consideration + that the node is not placed at the origin, but has been shifted + somewhere. However, the anchor positions are always specified in + the shape's ``private'' coordinate system. The ``outer'' + transformation that has been applied to the shape upon its + creation is applied automatically to the coordinates returned by + the anchor's \meta{code}. + + Out |simple rectangle| only has one text label (node + part) called |text|. This is the default situation, so we need not + do anything. For the |text| node part we must setup a |text| + anchor. This anchor is used upon creation of a node to determine + the lower left corner of the text label (within the private + coordinate system of the shape). By default, the |text| anchor is + at the origin, but you may change this. For example, we would say +\begin{codeexample}[code only] +\anchor{text}{% + \upperrightcorner% + \pgf@x=-\pgf@x% + \pgf@y=-\pgf@y% +} +\end{codeexample} + to center the text label on the origin in the shape coordinate + space. Note that we could \emph{not} have written the following: + +\begin{codeexample}[code only] +\anchor{text}{\pgfpoint{-.5\wd\pgfnodeparttextbox}{-.5\ht\pgfnodeparttextbox}} +\end{codeexample} + Do you see why this is wrong? The problem is that the box + |\pgfnodeparttextbox| will most likely not have the correct size + when the anchor is computed. After all, the anchor position might + be recomputed at a time when several other nodes have been created. + + If a shape has several node parts, we would have to define an + anchor for each part. + \end{command} + \begin{command}{\anchorborder\marg{code}} + A \emph{border anchor} is an anchor point on the border of the + shape. What exactly is considered as the ``border'' of the shape + depends on the shape. + + When the user request a point on the border of the shape using the + |\pgfpointshapeborder| command, the \meta{code} will be executed + to discern this point. When the execution of the \meta{code} + starts, the dimensions |\pgf@x| and |\pgf@y| will have been set to + a location $p$ in the shape's coordinate system. It is now the job of + the \meta{code} to setup |\pgf@x| and |\pgf@y| such that they + specify the point on the shape's border that lies on a straight + line from the shape's center to the point $p$. Usually, this is a + somewhat complicated computation, involving many case distinctions + and some basic math. + + For our |simple rectangle| we must compute a point on the border + of a rectangle whose one corner is the origin (ignoring the depth + for simplicity) and whose other corner is |\upperrightcorner|. The + following code might be used: +\begin{codeexample}[code only] +\anchorborder{% + % Call a function that computes a border point. Since this + % function will modify dimensions like \pgf@x, we must move them to + % other dimensions. + \@tempdima=\pgf@x + \@tempdimb=\pgf@y + \pgfpointborderrectangle{\pgfpoint{\@tempdima}{\@tempdimb}}{\upperrightcorner} +} +\end{codeexample} + \end{command} + \begin{command}{\backgroundpath\marg{code}} + This command specifies the path that ``makes up'' the background + of the shape. Note that the shape cannot prescribe what is going + to happen with the path: It might be drawn, shaded, filled, or + even thrown away. If you want to specify that something should + ``always'' happen when this shape is drawn (for example, if the + shape is a stop-sign, we \emph{always} want it to be filled with a + red color), you can use commands like |\beforebackgroundpath|, + explained below. + + When the \meta{code} is executed, all saved anchors will be in + effect. The \meta{code} should contain path construction + commands. + + For our |simple rectangle|, the following code might be used: +\begin{codeexample}[code only] +\backgroundpath{ + \pgfpathrectanglecorners + {\upperrightcorner} + {\pgfpointscale{-1}{\upperrightcorner}} +} +\end{codeexample} + As the name suggests, the background path is used ``behind'' the + text labels. Thus, this path is used first, then the text labels are + drawn, possibly obscuring part of the path. + \end{command} + \begin{command}{\foregroundpath\marg{code}} + This command works like |\backgroundpath|, only it is invoked + after the text labels have been drawn. This means that this path can + possibly obscure (part of) the text labels. + \end{command} + \begin{command}{\behindbackgroundpath\marg{code}} + Unlike the previous two commands, \meta{code} should not only + construct a path, it should also use this path in whatever way is + appropriate. For example, the \meta{code} might fill some area + with a uniform color. + + Whatever the \meta{code} does, it does it first. This means that + any drawing done by \meta{code} will be even behind the background + path. + + Note that the \meta{code} is protected with a |{pgfscope}|. + \end{command} + \begin{command}{\beforebackgroundpath\marg{code}} + This command works like |\behindbackgroundpath|, only the + \meta{code} is executed after the background path has been used, + but before the texts label are drawn. + \end{command} + \begin{command}{\behindforegroundpath\marg{code}} + The \meta{code} is executed after the text labels have been drawn, + but before the foreground path is used. + \end{command} + \begin{command}{\beforeforegroundpath\marg{code}} + This \meta{code} is executed at the very end. + \end{command} + \begin{command}{\inheritsavedanchors|[from=|\marg{another shape name}|]|} + This command allows you to inherit the code for saved anchors from + \meta{another shape name}. The idea is that if you wish to create + a new shape that is just a small modification of a another shape, + you can recycle the code used for \meta{another shape name}. + + The effect of this command is the same as if you had called + |\savedanchor| and |\saveddimen| for each saved anchor or saved + dimension declared in \meta{another shape name}. Thus, it is not + possible to ``selectively'' inherit only some saved anchors, you + always have to inherit all saved anchors from another + shape. However, you can inherit the saved anchors of more than one + shape by calling this command several times. + \end{command} + \begin{command}{\inheritbehindbackgroundpath|[from=|\marg{another shape name}|]|} + This command can be used to inherit the code used for the + drawings behind the background path from \meta{another shape name}. + \end{command} + \begin{command}{\inheritbackgroundpath|[from=|\marg{another shape name}|]|} + Inherits the background path code from \meta{another shape name}. + \end{command} + \begin{command}{\inheritbeforebackgroundpath|[from=|\marg{another shape name}|]|} + Inherits the before background path code from \meta{another shape name}. + \end{command} + \begin{command}{\inheritbehindforegroundpath|[from=|\marg{another shape name}|]|} + Inherits the behind foreground path code from \meta{another shape name}. + \end{command} + \begin{command}{\inheritforegroundpath|[from=|\marg{another shape name}|]|} + Inherits the foreground path code from \meta{another shape name}. + \end{command} + \begin{command}{\inheritbeforeforegroundpath|[from=|\marg{another shape name}|]|} + Inherits the before foreground path code from \meta{another shape name}. + \end{command} + \begin{command}{\inheritanchor|[from=|\marg{another shape name}|]|\marg{name}} + Inherits the code of one specific anchor named \meta{name} from + \meta{another shape name}. Thus, unlike saved anchors, which must + be inherited collectively, normal anchors can and must be + inherited individually. + \end{command} + \begin{command}{\inheritanchorborder|[from=|\marg{another shape name}|]|} + Inherits the border anchor code from \meta{another shape name}. + \end{command} + + The following example shows how a shape can be defined that relies + heavily on inheritance: +\makeatletter +\begin{codeexample}[] +\pgfdeclareshape{document}{ + \inheritsavedanchors[from=rectangle] % this is nearly a rectangle + \inheritanchorborder[from=rectangle] + \inheritanchor[from=rectangle]{center} + \inheritanchor[from=rectangle]{north} + \inheritanchor[from=rectangle]{south} + \inheritanchor[from=rectangle]{west} + \inheritanchor[from=rectangle]{east} + % ... and possibly more + \backgroundpath{% this is new + % store lower right in xa/ya and upper right in xb/yb + \southwest \pgf@xa=\pgf@x \pgf@ya=\pgf@y + \northeast \pgf@xb=\pgf@x \pgf@yb=\pgf@y + % compute corner of ``flipped page'' + \pgf@xc=\pgf@xb \advance\pgf@xc by-5pt % this should be a parameter + \pgf@yc=\pgf@yb \advance\pgf@yc by-5pt + % construct main path + \pgfpathmoveto{\pgfpoint{\pgf@xa}{\pgf@ya}} + \pgfpathlineto{\pgfpoint{\pgf@xa}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@ya}} + \pgfpathclose + % add little corner + \pgfpathmoveto{\pgfpoint{\pgf@xc}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}} + } +}\hskip-1.2cm +\begin{tikzpicture} + \node[shade,draw,shape=document,inner sep=2ex] (x) {Remark}; + \node[fill=examplefill,draw,ellipse,double] + at ([shift=(-80:3cm)]x) (y) {Use Case}; + + \draw[dashed] (x) -- (y); +\end{tikzpicture} +\end{codeexample} + +\end{command} + + + + +\subsection{Predefined Shapes} + +\begin{shape}{coordinate} + The |coordinate| is mainly intended to be used to store locations + using the node mechanism. This shape does not have any background + path and options like |draw| have no effect on it. Also, it does not + have any node parts, so no text is drawn when this shape is used. + + \tikzname\ handles this shape in a special way, see + Section~\ref{section-tikz-coordinate-shape}. +\end{shape} + +\begin{shape}{rectangle} + This shape is a rectangle tightly fitting the text box. Use inner or + outer separation to increase the distance between the text box and + the border and the anchors. The following figure shows the anchors + defined by this shape; the anchors |10| and |130| are example of border + anchors. +\begin{codeexample}[] +\Huge +\begin{tikzpicture} + \node[name=s,shape=rectangle,style=shape example] {Rectangle\vrule width 1pt height 2cm}; + \foreach \anchor/\placement in + {north west/above left, north/above, north east/above right, + west/left, center/above, east/right, + mid west/right, mid/above, mid east/left, + base west/left, base/below, base east/right, + south west/below left, south/below, south east/below right, + text/left, 10/right, 130/above} + \draw[shift=(s.\anchor)] plot[mark=x] coordinates {(0,0)} + node[\placement] {\scriptsize\texttt{(s.\anchor)}}; +\end{tikzpicture} +\end{codeexample} +\end{shape} + +\begin{shape}{circle} + This shape is a circle tightly fitting the text box. +\begin{codeexample}[] +\Huge +\begin{tikzpicture} + \node[name=s,shape=circle,style=shape example] {Circle\vrule width 1pt height 2cm}; + \foreach \anchor/\placement in + {north west/above left, north/above, north east/above right, + west/left, center/above, east/right, + mid west/right, mid/above, mid east/left, + base west/left, base/below, base east/right, + south west/below left, south/below, south east/below right, + text/left, 10/right, 130/above} + \draw[shift=(s.\anchor)] plot[mark=x] coordinates {(0,0)} + node[\placement] {\scriptsize\texttt{(s.\anchor)}}; +\end{tikzpicture} +\end{codeexample} +\end{shape} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex new file mode 100644 index 00000000000..4117a63eff7 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex @@ -0,0 +1,667 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Constructing Paths} + +\subsection{Overview} + +The ``basic entity of drawing'' in \pgfname\ is the \emph{path}. A +path consists of several parts, each of which is either a closed or +open curve. An open curve has a starting point and an end point and, +in between, consists of several \emph{segments}, each of which is +either a straight line or a Bézier curve. Here is an example of a +path (in red) consisting of two parts, one open, one closed: + +\begin{codeexample}[] +\begin{tikzpicture}[scale=2] + \draw[thick,red] + (0,0) coordinate (a) + -- coordinate (ab) (1,.5) coordinate (b) + .. coordinate (bc) controls +(up:1cm) and +(left:1cm) .. (3,1) coordinate (c) + (0,1) -- (2,1) -- coordinate (x) (1,2) -- cycle; + + \draw (a) node[below] {start part 1} + (ab) node[below right] {straight segment} + (b) node[right] {end first segment} + (c) node[right] {end part 1} + (x) node[above right] {part 2 (closed)}; +\end{tikzpicture} +\end{codeexample} + +A path, by itself, has no ``effect,'' that is, it does not leave any +marks on the page. It is just a set of points on the plane. However, +you can \emph{use} a path in different ways. The most natural actions +are \emph{stroking} (also known as \emph{drawing}) and +\emph{filling}. Stroking can be imagined as picking up a pen of a +certain diameter and ``moving it along the path.'' Filling means that +everything ``inside'' the path is filled with a uniform +color. Naturally, the open parts of a path must first be closed before +a path can be filled. + +In \pgfname, there are numerous commands for constructing paths, all +of which start with |\pgfpath|. There are also commands for +\emph{using} paths, though most operations can be performed by calling +|\pgfusepath| with an appropriate parameter. + +As a side-effect, the path construction commands keep track of two +bounding boxes. One is the bounding box for the current path, the +other is a bounding box for all paths in the current picture. See +Section~\ref{section-bb} for more details. + +Each path construction command extends the current path in some +way. The ``current path'' is a global entity that persists across +\TeX\ groups. Thus, between calls to the path construction commands +you can perform arbitrary computations and even open and closed \TeX\ +groups. The current path only gets ``flushed'' when the |\pgfusepath| +command is called (or when the soft-path subsystem is used directly, +see Section~\ref{section-soft-paths}). + +\subsection{The Move-To Path Operation} + +The most basic operation is the move-to operation. It must be given at +the beginning of paths, though some path construction command (like +|\pgfpathrectangle|) generate move-tos implicitly. A move-to operation +can also be used to start a new part of a path. + +\begin{command}{\pgfpathmoveto\marg{coordinate}} + This command expects a \pgfname-coordinate like |\pgfpointorigin| as + its parameter. When the current path is empty, this operation will + start the path at the given \meta{coordinate}. If a path has already + been partly constructed, this command will end the current part of + the path and start a new one. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}} + \pgfpathlineto{\pgfpoint{3cm}{0.5cm}} + \pgfpathlineto{\pgfpoint{3cm}{0cm}} + \pgfsetfillcolor{examplefill} + \pgfusepath{fill,stroke} +\end{pgfpicture} +\end{codeexample} +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}} + \pgfpathmoveto{\pgfpoint{2cm}{1cm}} % New part + \pgfpathlineto{\pgfpoint{3cm}{0.5cm}} + \pgfpathlineto{\pgfpoint{3cm}{0cm}} + \pgfsetfillcolor{examplefill} + \pgfusepath{fill,stroke} +\end{pgfpicture} +\end{codeexample} + The command will apply the current coordinate transformation matrix + to \meta{coordinate} before using it. + + The command will update the bounding box of the current path and + picture, if necessary. +\end{command} + + +\subsection{The Line-To Path Operation} + +\begin{command}{\pgfpathlineto\marg{coordinate}} + This command extends the current path in a straight line to the + given \meta{coordinate}. If this command is given at the beginning + of path without any other path construction command given before (in + particular without a move-to operation), the \TeX\ file may compile + without an error message, but a viewer application may display an + error message when trying to render the picture. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}} + \pgfsetfillcolor{examplefill} + \pgfusepath{fill,stroke} +\end{pgfpicture} +\end{codeexample} + The command will apply the current coordinate transformation matrix + to \meta{coordinate} before using it. + + The command will update the bounding box of the current path and + picture, if necessary. +\end{command} + + +\subsection{The Curve-To Path Operation} + +\begin{command}{\pgfpathcurveto\marg{support 1}\marg{support 2}\marg{coordinate}} + This command extends the current path with a Bézier curve from the + last point of the path to \meta{coordinate}. The \meta{support 1} + and \meta{support 2} are the first and second support point of the + Bézier curve. For more information on Bézier curve, please consult a + standard textbook on computer graphics. + + Like the line-to command, this command may not be the first path + construction command in a path. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{1cm}}{\pgfpoint{3cm}{0cm}} + \pgfsetfillcolor{examplefill} + \pgfusepath{fill,stroke} +\end{pgfpicture} +\end{codeexample} + The command will apply the current coordinate transformation matrix + to \meta{coordinate} before using it. + + The command will update the bounding box of the current path and + picture, if necessary. However, the bounding box is simply made + large enough such that it encompasses all of the support points and + the \meta{coordinate}. This will guarantee that the curve is + completely inside the bounding box, but the bounding box will + typically be quite a bit too large. It is not clear (to me) how this + can be avoided without resorting to ``some serious math'' in order + to calculate a precise bounding box. +\end{command} + + +\subsection{The Close Path Operation} + +\begin{command}{\pgfpathclose} + This command closes the current part of the path by appending a + straight line to the start point of the current part. Note that there + \emph{is} a difference between closing a path and using the line-to + operation to add a straight line to the start of the current + path. The difference is demonstrated by the upper corners of the triangles + in the following example: +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{5pt} + \pgfpathmoveto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{0cm}{-1cm}} + \pgfpathlineto{\pgfpoint{1cm}{-1cm}} + \pgfpathclose + \pgfpathmoveto{\pgfpoint{2.5cm}{1cm}} + \pgfpathlineto{\pgfpoint{1.5cm}{-1cm}} + \pgfpathlineto{\pgfpoint{2.5cm}{-1cm}} + \pgfpathlineto{\pgfpoint{2.5cm}{1cm}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\subsection{Arc, Ellipse and Circle Path Operations} + +The path construction commands that we have discussed up to now are +sufficient to create all paths that can be created ``at all.'' +However, it is useful to have special commands to create certain +shapes, like circles, that arise often in practice. + +In the following, the commands for adding (parts of) (transformed) +circles to a path are described. + +\begin{command}{\pgfpatharc\marg{start angle}\marg{end + angle}\marg{radius}} + This command appends a part of a circle (or an ellipse) to the current + path. Imaging the curve between \meta{start angle} and \meta{end + angle} on a circle of radius \meta{radius} (if $\meta{start angle} + < \meta{end angle}$, the curve goes around the circle + counterclockwise, otherwise clockwise). This curve is now moved such + that the point where the curve starts is the previous last point of the + path. Note that this command will \emph{not} start a new part of the + path, which is important for example for filling purposes. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{0cm}{1cm}} + \pgfpatharc{180}{90}{.5cm} + \pgfpathlineto{\pgfpoint{3cm}{1.5cm}} + \pgfpatharc{90}{-45}{.5cm} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} + + Saying |\pgfpatharc{0}{360}{1cm}| ``nearly'' gives you a full + circle. The ``nearly'' refers to the fact that the circle will not + be closed. You can close it using |\pgfpathclose|. + + The \meta{radius} need not always be a single \TeX\ + dimension. Instead, it can also contain a slash, in which case it + must consist of two dimensions separated by this slash. In this + case the first dimension is the $x$-radius and the second the + $y$-radius of the ellipse from which the curve is taken: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharc{180}{45}{2cm/1cm} + \pgfusepath{draw} +\end{tikzpicture} +\end{codeexample} + + The axes of the circle or ellipse from which the arc is ``taken'' + always point up and right. However, the current coordinate + transformation matrix will have an effect on the arc. This can be + used to, say, rotate an arc: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformrotate{30} + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharc{180}{45}{2cm/1cm} + \pgfusepath{draw} +\end{tikzpicture} +\end{codeexample} + + The command will update the bounding box of the current path and + picture, if necessary. Unless rotation or shearing transformations + are applied, the bounding box will be tight. +\end{command} + +\begin{command}{\pgfpathellipse\marg{center}\marg{first + axis}\marg{second axis}} + The effect of this command is to append an ellipse to the current + path (if the path is not empty, a new part is started). The + ellipse's center will be \meta{center} and \meta{first axis} and + \meta{second axis} are the axis \emph{vectors}. The same effect as + this command can also be achieved using an appropriate sequence of + move-to, arc, and close operations, but this command is easier and + faster. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathellipse{\pgfpoint{1cm}{0cm}} + {\pgfpoint{1.5cm}{0cm}} + {\pgfpoint{0cm}{1cm}} + \pgfusepath{draw} + \color{red} + \pgfpathellipse{\pgfpoint{1cm}{0cm}} + {\pgfpoint{1cm}{1cm}} + {\pgfpoint{-0.5cm}{0.5cm}} + \pgfusepath{draw} +\end{tikzpicture} +\end{codeexample} + + The command will apply coordinate transformations to all coordinates + of the ellipse. However, the coordinate transformations are applied + only after the ellipse is ``finished conceptually.'' Thus, a + transformation of 1cm to the right will simply shift the ellipse one + centimeter to the right; it will not add 1cm to the $x$-coordinates + of the two axis vectors. + + The command will update the bounding box of the current path and + picture, if necessary. +\end{command} + +\begin{command}{\pgfpathcirlce\marg{center}\marg{radius}} + A shorthand for |\pgfpathellipse| applied to \meta{center} and the + two axis vectors $(\meta{radius},0)$ and $(0,\meta{radius})$. +\end{command} + + +\subsection{Rectangle Path Operations} + +Another shape that arises frequently is the rectangle. Two commands +can be used to add a rectangle to the current path. Both commands will +start a new part of the path. + + +\begin{command}{\pgfpathrectangle\marg{corner}\marg{diagonal vector}} + Adds a rectangle to the path whose one corner is \meta{corner} and + whose opposite corner is given by $\meta{corner} + \meta{diagonal + vector}$. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathrectangle{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1.5cm}{0.25cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfpathrectangle{\pgfpoint{2cm}{0.5cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfusepath{draw} +\end{tikzpicture} +\end{codeexample} + The command will apply coordinate transformations and update the + bounding boxes tightly. +\end{command} + + +\begin{command}{\pgfpathrectanglecorners\marg{corner}\marg{opposite corner}} + Adds a rectangle to the path whose two opposing corners are + \meta{corner} and \meta{opposite corner}. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathrectanglecorners{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfusepath{draw} +\end{tikzpicture} +\end{codeexample} + The command will apply coordinate transformations and update the + bounding boxes tightly. +\end{command} + + + +\subsection{The Grid Path Operation} + +\begin{command}{\pgfpathgrid\oarg{options}\marg{lower left}\marg{upper right}} + Appends a grid to the current path. That is, a (possibly large) + number of parts are added to the path, each part consisting of a + single horizontal or vertical straight line segment. + + Conceptually, the origin is part of the grid and the grid is clipped + to the rectangle specified by the \meta{lower left} and + the \meta{upper right} corner. However, no clipping occurs (this + command just adds parts to the current path). Rather, the points + where the lines enter and leave the ``clipping area'' are computed + and used to add simple lines to the current path. + + Allowed \meta{options} are: + \begin{itemize} + \itemoption{stepx}|=|\meta{dimension} + Sets the horizontal stepping to \meta{dimension}. Default is 1cm. + \itemoption{stepy}|=|\meta{dimension} + Sets the vertical stepping to \meta{dimension}. Default is 1cm. + \itemoption{step}|=|\meta{vector} + Sets the horizontal stepping to the $x$-coordinate of + \meta{vector} and the vertical stepping to its $y$-coordinate. + \end{itemize} +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetlinewidth{0.8pt} + \pgfpathgrid[step={\pgfpoint{1cm}{1cm}}] + {\pgfpoint{-3mm}{-3mm}}{\pgfpoint{33mm}{23mm}} + \pgfusepath{stroke} + \pgfsetlinewidth{0.4pt} + \pgfpathgrid[stepx=1mm,stepy=1mm] + {\pgfpoint{-1.5mm}{-1.5mm}}{\pgfpoint{31.5mm}{21.5mm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + The command will apply coordinate transformations and update the + bounding boxes tightly. As for ellipses, the transformations are + applied to the ``conceptually finished'' grid. +\begin{codeexample}[] +\begin{pgfpicture} + \pgftransformrotate{10} + \pgfpathgrid[stepx=1mm,stepy=2mm]{\pgfpoint{0mm}{0mm}}{\pgfpoint{30mm}{30mm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + + +\subsection{The Parabola Path Operation} + +\begin{command}{\pgfpathparabola\marg{bend vector}\marg{end vector}} + This command appends two half-parabolas to the current path. The + first starts at the current point and ends at the current point plus + \meta{bend vector}. At his point, it has its bend. The second half + parabola starts at that bend point and end at point that is given by + the bend plus \meta{end vector}. + + If you set \meta{end vector} to the null vector, you append only a + half parabola that goes from the current point to the bend; by + setting \meta{bend vector} to the null vector, you append only a + half parabola that goes to current point plus \meta{end vector} and + has its bend at the current point. + + It is not possible to use this command to draw a part of a parabola + that does not contain the bend. + +\begin{codeexample}[] +\begin{pgfpicture} + % Half-parabola going ``up and right'' + \pgfpathmoveto{\pgfpointorigin} + \pgfpathparabola{\pgfpointorigin}{\pgfpoint{2cm}{4cm}} + \color{red} + \pgfusepath{stroke} + + % Half-parabola going ``down and right'' + \pgfpathmoveto{\pgfpointorigin} + \pgfpathparabola{\pgfpoint{-2cm}{4cm}}{\pgfpointorigin} + \color{blue} + \pgfusepath{stroke} + + % Full parabola + \pgfpathmoveto{\pgfpoint{-2cm}{2cm}} + \pgfpathparabola{\pgfpoint{1cm}{-1cm}}{\pgfpoint{2cm}{4cm}} + \color{orange} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + The command will apply coordinate transformations and update the + bounding boxes. +\end{command} + + +\subsection{Sine and Cosine Path Operations} + +Sine and cosine curves often need to be drawn and the following commands +may help with this. However, they only allow you to append sine and +cosine curves in intervals that are multiples of $\pi/2$. + +\begin{command}{\pgfpathsine\marg{vector}} + This command appends a sine curve in the interval $[0,\pi/2]$ to the + current path. The sine curve is squeezed or stretched such that the + curve starts at the current point and ends at the current point plus + \meta{vector}. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,1); + \pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathsine{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} + + \color{red} + \pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathsine{\pgfpoint{-2cm}{-2cm}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + The command will apply coordinate transformations and update the + bounding boxes. +\end{command} + +\begin{command}{\pgfpathcosine\marg{vector}} + This command appends a cosine curve in the interval $[0,\pi/2]$ to the + current path. The curve is squeezed or stretched such that the + curve starts at the current point and ends at the current point plus + \meta{vector}. Using several sine and cosine operations in sequence + allows you to produce a complete sine or cosine curve +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpoint{0cm}{0cm}} + \pgfpathsine{\pgfpoint{1cm}{1cm}} + \pgfpathcosine{\pgfpoint{1cm}{-1cm}} + \pgfpathsine{\pgfpoint{1cm}{-1cm}} + \pgfpathcosine{\pgfpoint{1cm}{1cm}} + \pgfsetfillcolor{examplefill} + \pgfusepath{fill,stroke} +\end{pgfpicture} +\end{codeexample} + The command will apply coordinate transformations and update the + bounding boxes. +\end{command} + + +\subsection{Plot Path Operations} + +There exist several commands for appending +plots to a path. These +commands are available through the package |pgfbaseplot|. They are +documented in Section~\ref{section-plots}. + + +\subsection{Rounded Corners} + +Normally, when you connect two straight line segments or when you +connect two curves that end and start ``at different angles'' you get +``sharp corners'' between the lines or curves. In some cases it is +desirable to produce ``rounded corners'' instead. Thus, the lines +or curves should be shortened a bit and then connected by arcs. + +\pgfname\ offers an easy way to achieve this effect, by calling the +following two commands. + +\begin{command}{\pgfsetcornersarced\marg{point}} + This command causes all subsequent corners to be replaced by little + arcs. The effect of this command lasts till the end of the current + \TeX\ scope. + + The \meta{point} dictates how large the corner arc will be. Consider + a corner made by two lines $l$ and~$r$ and assume that the line $l$ + comes first on the path. The $x$-dimension of the \meta{point} + decides by how much the line~$l$ will be shortened, the + $y$-dimension of \meta{point} decides by how much the line $r$ will + be shortened. Then, the shortened lines are connected by an arc. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \pgfsetcornersarced{\pgfpoint{5mm}{5mm}} + \pgfpathrectanglecorners{\pgfpointorigin}{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \pgfsetcornersarced{\pgfpoint{10mm}{5mm}} + % 10mm entering, + % 5mm leaving. + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{0cm}{2cm}} + \pgfpathlineto{\pgfpoint{3cm}{2cm}} + \pgfpathcurveto + {\pgfpoint{3cm}{0cm}} + {\pgfpoint{2cm}{0cm}} + {\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + + If the $x$- and $y$-coordinates of \meta{point} are the same and the + corner is a right angle, you will get a perfect quarter circle + (well, not quite perfect, but perfect up to six decimals). When the + angle is not $90^\circ$, you only get a fair approximation. + + More or less ``all'' corners will be rounded, even the corner + generated by a |\pgfpathclose| command. (The author is a bit proud + of this feature.) + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetcornersarced{\pgfpoint{4pt}{4pt}} + \pgfpathmoveto{\pgfpointpolar{0}{1cm}} + \pgfpathlineto{\pgfpointpolar{72}{1cm}} + \pgfpathlineto{\pgfpointpolar{144}{1cm}} + \pgfpathlineto{\pgfpointpolar{216}{1cm}} + \pgfpathlineto{\pgfpointpolar{288}{1cm}} + \pgfpathclose + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + + To return to normal (unrounded) corners, use + |\pgfsetcornersarced{\pgfpointorigin}|. + + Note that the rounding will produce strange and undesirable effects + if the lines at the corners are too short. In this case the + shortening may cause the lines to ``suddenly extend over the other + end'' which is rarely desirable. +\end{command} + + + + +\subsection{Internal Tracking of Bounding Boxes for Paths and Pictures} + +\label{section-bb} + +\makeatletter + +The path construction commands keep track of two bounding boxes: One +for the current path, which is reset whenever the path is used and +thereby flushed, and a bounding box for the current |{pgfpicture}|. + +The bounding boxes are not accessible by ``normal'' macros. Rather, +two sets of four dimension variables are used for this, all of which +contain the letter~|@|. + +\begin{textoken}{\pgf@pathminx} + The minimum $x$-coordinate ``mentioned'' in the current + path. Initially, this is set to $16000$pt. +\end{textoken} + +\begin{textoken}{\pgf@pathmaxx} + The maximum $x$-coordinate ``mentioned'' in the current + path. Initially, this is set to $-16000$pt. +\end{textoken} + +\begin{textoken}{\pgf@pathminy} + The minimum $y$-coordinate ``mentioned'' in the current + path. Initially, this is set to $16000$pt. +\end{textoken} + +\begin{textoken}{\pgf@pathmaxy} + The maximum $y$-coordinate ``mentioned'' in the current + path. Initially, this is set to $-16000$pt. +\end{textoken} + +\begin{textoken}{\pgf@picminx} + The minimum $x$-coordinate ``mentioned'' in the current + picture. Initially, this is set to $16000$pt. +\end{textoken} + +\begin{textoken}{\pgf@picmaxx} + The maximum $x$-coordinate ``mentioned'' in the current + picture. Initially, this is set to $-16000$pt. +\end{textoken} + +\begin{textoken}{\pgf@picminy} + The minimum $y$-coordinate ``mentioned'' in the current + picture. Initially, this is set to $16000$pt. +\end{textoken} + +\begin{textoken}{\pgf@picmaxy} + The maximum $y$-coordinate ``mentioned'' in the current + picture. Initially, this is set to $-16000$pt. +\end{textoken} + + +Each time a path construction command is called, the above variables +are (globally) updated. To facilitate this, you can use the following +command: + +\begin{command}{\pgf@protocolsizes\marg{x-dimension}\marg{y-dimension}} + Updates all of the above dimension in such a way that the point + specified by the two arguments is inside both bounding boxes. For + the picture's bounding box this updating occurs only if + |\ifpgf@relevantforpicturesize| is true, see below. +\end{command} + +For the bounding box of the picture it is not always desirable that +every path construction command affects this bounding box. For +example, if you have just used a clip command, you do not want anything +outside the clipping area to affect the bounding box. For this reason, +there exists a special ``\TeX\ if'' that (locally) decides whether +updating should be applied to the picture's bounding box. Clipping +will set this if to false, as will certain other commands. + +\begin{command}{\pgf@relevantforpicturesizefalse} + Suppresses updating of the picture's bounding box. +\end{command} + +\begin{command}{\pgf@relevantforpicturesizetrue} + Causes updating of the picture's bounding box. +\end{command} + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex new file mode 100644 index 00000000000..5c5a1738bc8 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex @@ -0,0 +1,365 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Creating Plots} + +\label{section-plots} + +This section describes the |pgfbaseplot| package. + +\begin{package}{pgfbaseplot} + This package provides a set of commands that are intended to make it + reasonably easy to plot functions using \pgfname. It is loaded + automatically by |pgf|, but you can load it manually if you have + only included |pgfcore|. +\end{package} + +\subsection{Overview} + +\subsubsection{When Should One Use PGF for Generating Plots? } + +There exist many powerful programs that produce plots, examples are +\textsc{gnuplot} or \textsc{mathematica}. These programs can produce +two different kinds of output: First, they can output a complete plot +picture in a certain format (like \pdf) that includes all low-level +commands necessary for drawing the complete plot (including axes and +labels). Second, they can usually also produce ``just plain data'' in +the form of a long list of coordinates. Most of the powerful programs +consider it a to be ``a bit boring'' to just output tabled data and +very much prefer to produce fancy pictures. Nevertheless, when coaxed, +they can also provide the plain data. + +The plotting mechanism described in the following deals only with +plotting data given in the form of a list of coordinates. Thus, this +section is about using \pgfname\ to turn lists of coordinates into +plots. + +\emph{Note that is often not necessary to use \pgfname\ for this.} +Programs like \textsc{gnuplot} can produce very sophisticated plots +and it is usually much easier to simply include these plots as a +finished \textsc{pdf} or PostScript graphics. + +However, there are a number of reasons why you may wish to invest time +and energy into mastering the \pgfname\ commands for creating plots: + +\begin{itemize} +\item + Virtually all plots produced by ``external programs'' use different + fonts from the one used in your document. +\item + Even worse, formulas will look totally different, if they can be + rendered at all. +\item + Line width will usually be too large or too small. +\item + Scaling effects upon inclusion can create a mismatch between sizes + in the plot and sizes in the text. +\item + The automatic grid generated by most programs is mostly + distracting. +\item + The automatic ticks generated by most programs are cryptic + numerics. (Try adding a tick reading ``$\pi$'' at the right point.) +\item + Most programs make it very easy to create ``chart junk'' in a most + convenient fashion. All show, no content. +\item + Arrows and plot marks will almost never match the arrows used in the + rest of the document. +\end{itemize} + +The above list is not exhaustive, unfortunately. + + +\subsubsection{How PGF Handles Plots} + +\pgfname\ (conceptually) uses a two-stage process for generating +plots. First, a \emph{plot stream} must be produced. This stream +consists (more or less) of a large number of coordinates. Second a +\emph{plot handler} is applied to the stream. A plot handler ``does +something'' with the stream. The standard handler will issue +line-to operations to the coordinates in the stream. However, a +handler might also try to issue appropriate curve-to operations in +order to smooth the curve. A handler may even do something else +entirely, like writing each coordinate to another stream, thereby +duplicating the original stream. + +Both for the creation of streams and the handling of streams different +sets of commands exist. The commands for creating streams start with +|\pgfplotstream|, the commands for setting the handler start with +|\pgfplothandler|. + + + +\subsection{Generating Plot Streams} + +\subsubsection{Basic Building Blocks of Plot Streams} +A \emph{plot stream} is a (long) sequence of the following three +commands: +\begin{enumerate} +\item + |\pgfplotstreamstart|, +\item + |\pgfplotstreampoint|, and +\item + |\pgfplotstreamend|. +\end{enumerate} +Between calls of these commands arbitrary other code may be +called. Obviously, the stream should start with the first command and +end with the last command. Here is an example of a plot stream: +\begin{codeexample}[code only] +\pgfplotstreamstart +\pgfplotstreampoint{\pgfpoint{1cm}{1cm}} +\newdimen\mydim +\mydim=2cm +\pgfplotstreampoint{\pgfpoint{\mydim}{2cm}} +\advance \mydim by 3cm +\pgfplotstreampoint{\pgfpoint{\mydim}{2cm}} +\pgfplotstreamend +\end{codeexample} + +\begin{command}{\pgfplotstreamstart} + This command signals that a plot stream starts. The effect of this + command is to call the internal command |\pgf@plotstreamstart|, + which is set by the current plot handler to do whatever needs to be + done at the beginning of the plot. +\end{command} + +\begin{command}{\pgfplotstreampoint\marg{point}} + This command adds a \meta{point} to the current plot stream. The + effect of this command is to call the internal command |\pgf@plotstreampoint|, + which is also set by the current plot handler. This command should + now ``handle'' the point in some sensible way. For example, a + line-to command might be issued for the point. +\end{command} + +\begin{command}{\pgfplotstreamend} + This command signals that a plot stream ends. It calls + |\pgf@plotstreamend|, which should now do any necessary ``cleanup.'' +\end{command} + +Note that plot streams are not buffered, that is, the different points +are handled immediately. However, using the recording handler, it is +possible to record a stream. + +\subsubsection{Commands That Generate Plot Streams} + +Plot streams can be created ``by hand'' as in the earlier +example. However, most of the time the coordinates will be produced +internally by some command. For example, the |\pgfplotxyfile| reads a +file and converts it into a plot stream. + +\begin{command}{\pgfplotxyfile\marg{filename}} + This command will try to open the file \meta{filename}. If this + succeeds, it will convert the file contents into a plot stream as + follows: A |\pgfplotstreamstart| is issued. Then, each nonempty line + of the file should start with two numbers separated by a space, such + as |0.1 1| or |100 -.3|. Anything following the numbers is ignored. + + Each pair \meta{x} and \meta{y} of numbers is converted into one + plot stream point in the xy-coordinate system. Thus, a line like +\begin{codeexample}[code only] +2 -5 some text +\end{codeexample} + is turned into +\begin{codeexample}[code only] +\pgfplotstreampoint{\pgfpointxy{2}{-5}} +\end{codeexample} + + The two characters |%| and |#| are also allowed in a file and they + are both treated as comment characters. Thus, a line starting with + either of them is empty and, hence, ignored. + + When the file has been read completely, |\pgfplotstreamend| is + called. +\end{command} + + +\begin{command}{\pgfplotxyzfile\marg{filename}} + This command works like |\pgfplotxyfile|, only \emph{three} numbers + are expected on each non-empty line. They are converted into points + in the xyz-coordinate system. Consider, the following file: +\begin{codeexample}[code only] +% Some comments +# more comments +2 -5 1 first entry +2 -.2 2 second entry +2 -5 2 third entry +\end{codeexample} + It is turned into the following stream: +\begin{codeexample}[code only] +\pgfplotstreamstart +\pgfplotstreampoint{\pgfpointxyz{2}{-5}{1}} +\pgfplotstreampoint{\pgfpointxyz{2}{-.2}{2}} +\pgfplotstreampoint{\pgfpointxyz{2}{-5}{2}} +\pgfplotstreamend +\end{codeexample} +\end{command} + + +Currently, there is no command that can decide automatically whether +the xy-coordinate system should be used or whether the xyz-system +should be used. However, it would not be terribly difficult to write a +``smart file reader'' that parses coordinate files a bit more +intelligently. + + +\begin{command}{\pgfplotgnuplot\oarg{prefix}\marg{function}} + This command will ``try'' to call the \textsc{gnuplot} program to + generate the coordinates of the \meta{function}. In detail, the + following happens: + + This command works with two files: \meta{prefix}|.gnuplot| and + \meta{prefix}|.table|. If the optional argument \meta{prefix} is + not given, it is set to |\jobname|. + + Let us start with the situation where none of these files + exists. Then \pgfname\ will first generate the file + \meta{prefix}|.gnuplot|. In this file it writes +\begin{codeexample}[code only] +set terminal table; set output "#1.table"; set format "%.5f" +\end{codeexample} + where |#1| is replaced by \meta{prefix}. Then, in a second line, it + writes the text \meta{function}. + + Next, \pgfname\ will try to invoke the program |gnuplot| with the + argument \meta{prefix}|.gnuplot|. This call may or may not succeed, + depending on whether the |\write18| mechanism (also known as + shell escape) is switched on and whether the |gnuplot| program is + available. + + Assuming that the call succeeded, the next step is to invoke + |\pgfplotxyfile| on the file \meta{prefix}|.table|; which is exactly + the file that has just been created by |gnuplot|. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,-1) grid (4,1); + \pgfplothandlerlineto + \pgfplotgnuplot[plots/pgfplotgnuplot-example]{plot [x=0:3.5] x*sin(x)} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + + The more difficult situation arises when the |.gnuplot| file exists, + which will be the case on the second run of \TeX\ on the \TeX\ + file. In this case \pgfname\ will read this file and check whether + it contains exactly what \pgfname\ ``would have written'' into + this file. If this is not the case, the file contents is overwritten + with what ``should be there'' and, as above, |gnuplot| is invoked to + generate a new |.table| file. However, if the file contents is ``as + expected,'' the external |gnuplot| program is \emph{not} + called. Instead, the \meta{prefix}|.table| file is immediately + read. + + As explained in Section~\ref{section-tikz-gnuplot}, the net effect + of the above mechanism is that |gnuplot| is called as little as + possible and that when you pass along the |.gnuplot| and |.table| + files with your |.tex| file to someone else, that person can + \TeX\ the |.tex| file without having |gnuplot| installed and without + having the |\write18| mechanism switched on. +\end{command} + + + +\subsection{Plot Handlers} + +\label{section-plot-handlers} + +A \emph{plot handler} prescribes what ``should be done'' with a +plot stream. You must set the plot handler before the stream starts. +The following commands install the most basic plot handlers; more plot +handlers are defined in the file |pgflibraryplothandlers|, which is +documented in Section~\ref{section-library-plothandlers}. + +All plot handlers work by setting redefining the following three +macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and +|\pgf@plotstreamend|. + +\begin{command}{\pgfplothandlerlineto} + This handler will issue a |\pgfpathlineto| command for each point of + the plot, \emph{except} possibly for the first. What happens with + the first point can be specified using the two commands described + below. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfplothandlerlineto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{3cm}{2cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetmovetofirstplotpoint} + Specifies that the line-to plot handler (and also some other plot + handlers) should issue a move-to command for the + first point of the plot instead of a line-to. This will start a new + part of the current path, which is not always, but often, + desirable. This is the default. +\end{command} + +\begin{command}{\pgfsetlinetofirstplotpoint} + Specifies that plot handlers should issue a line-to command for the + first point of the plot. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfsetlinetofirstplotpoint + \pgfplothandlerlineto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{3cm}{2cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfplothandlerdiscard} + This handler will simply throw away the stream. +\end{command} + +\begin{command}{\pgfplothandlerrecord\marg{macro}} + When this handler is installed, each time a plot stream command is + called, this command will be appended to \meta{macros}. Thus, at + the end of the stream, \meta{macro} will contain all the + commands that were issued on the stream. You can then install + another handler and invoke \meta{macro} to ``replay'' the stream + (possibly many times). + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfplothandlerrecord{\mystream} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{3cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} + \pgfplotstreamend + \pgfplothandlerlineto + \mystream + \pgfplothandlerclosedcurve + \mystream + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex new file mode 100644 index 00000000000..9c1a821e26c --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex @@ -0,0 +1,452 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Specifying Coordinates} + +\label{section-points} + +\subsection{Overview} + +Most \pgfname\ commands expect you to provide the coordinates of a +\emph{point} (also called \emph{coordinate}) inside your +picture. Points are always ``local'' to your picture, that is, they +never refer to an absolute position on the page, but to a position +inside the current |{pgfpicture}| environment. To specify a coordinate +you can use commands that start with |\pgfpoint|. + +\subsection{Basic Coordinate Commands} + +The following commands are the most basic for specifying a +coordinate. + +\begin{command}{\pgfpoint\marg{x coordinate}\marg{y coordinate}} + Yields a point location. The coordinates are given as \TeX\ + dimensions. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpoint{1cm}{1cm}} {2pt} + \pgfpathcircle{\pgfpoint{2cm}{5pt}} {2pt} + \pgfpathcircle{\pgfpoint{0pt}{.5in}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpointorigin} + Yields the origin. Same as |\pgfpoint{0pt}{0pt}|. +\end{command} + +\begin{command}{\pgfpointpolar\marg{degree}\marg{radius}} + Yields a point location given in polar coordinates. You can specify + the angle only in degrees, radians are not supported, currently. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \foreach \angle in {0,10,...,90} + {\pgfpathcircle{\pgfpointpolar{\angle}{1cm}}{2pt}} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + + + +\subsection{Coordinates in the Xy- and Xyz-Coordinate Systems} + +Coordinates can also be specified as multiples of an $x$-vector and a +$y$-vector. Normally, the $x$-vector points one centimeter in the +$x$-direction and the $y$-vector points one centimeter in the +$y$-direction, but using the commands |\pgfsetxvec| and +|\pgfsetyvec| they can be changed. Note that the $x$- and +$y$-vector do not necessarily point ``horizontally'' and +``vertically.'' + +It is also possible to specify a point as a multiple of three vectors, +the $x$-, $y$-, and $z$-vector. This is useful for creating simple +three dimensional graphics. + +\begin{command}{\pgfpointxy\marg{$s_x$}\marg{$s_y$}} + Yields a point that is situated at $s_x$ times the + $x$-vector plus $s_y$ times the $y$-vector. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpointxyz\marg{$s_x$}\marg{$s_y$}\marg{$s_z$}} + Yields a point that is situated at $s_x$ times the + $x$-vector plus $s_y$ times the $y$-vector plus $s_z$ times the + $z$-vector. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetarrowsend{to} + + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{0}{0}{1}} + \pgfusepath{stroke} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{0}{1}{0}} + \pgfusepath{stroke} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{1}{0}{0}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfsetxvec\marg{point}} + Sets that current $x$-vector for usage in the $xyz$-coordinate + system. + \example +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} + + \color{red} + \pgfsetxvec{\pgfpoint{0.75cm}{0cm}} + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetyvec\marg{point}} + Works like |\pgfsetyvec|. +\end{command} + +\begin{command}{\pgfsetzvec\marg{point}} + Works like |\pgfsetzvec|. +\end{command} + + + + +\subsection{Building Coordinates From Other Coordinates} + +Many commands allow you to construct a coordinate in terms of other +coordinates. + + +\subsubsection{Basic Manipulations of Coordinates} + +\begin{command}{\pgfpointadd\marg{$v_1$}\marg{$v_2$}} + Returns the sum vector $\meta{$v_1$} + \meta{$v_2$}$. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpointadd{\pgfpoint{1cm}{0cm}}{\pgfpoint{1cm}{1cm}}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpointscale\marg{factor}\marg{coordinate}} + Returns the vector $\meta{factor}\meta{coordinate}$. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpointscale{1.5}{\pgfpoint{1cm}{0cm}}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpointdiff\marg{start}\marg{end}} + Returns the difference vector $\meta{end} - \meta{start}$. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpointdiff{\pgfpoint{1cm}{0cm}}{\pgfpoint{1cm}{1cm}}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfpointnormalised\marg{point}} + This command returns a normalized version of \meta{point}, that is, + a vector of length 1pt pointing in the direction of \meta{point}. If + \meta{point} is the $0$-vector or extremely short, a vector of + length 1pt pointing upwards is returned. + + This command is \emph{not} implemented by calculating the length of + the vector, but rather by calculating the angle of the vector and + then using (something equivalent to) the |\pgfpointpolar| + command. This ensures that the point will really have length 1pt, + but it is not guaranteed that the vector will \emph{precisely} point + in the direction of \meta{point} due to the fact that the polar + tables are accurate only up to one degree. Normally, this is not a + problem. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt} + \pgfpathcircle{\pgfpointscale{20} + {\pgfpointnormalised{\pgfpoint{2cm}{1cm}}}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\subsubsection{Points Traveling along Lines and Curves} + +\label{section-pointsattime} + +The commands in this section allow you to specify points on a line or +a curve. Imaging a point ``traveling'' along a curve from some point +$p$ to another point $q$. At time $t=0$ the point is at $p$ and at +time $t=1$ it is at $q$ and at time, say, $t=1/2$ it is ``somewhere in +the middle.'' The exact location at time $t=1/2$ will not necessarily +be the ``halfway point,'' that is, the point whose distance on the +curve from $p$ and $q$ is equal. Rather, the exact location will +depend on the ``speed'' at which the point is traveling, which in +turn depends on the lengths of the support vectors in a complicated +manner. If you are interested in the details, please see a good book +on Bézier curves. + + + +\begin{command}{\pgfpointlineattime\marg{time $t$}\marg{point $p$}\marg{point $q$}} + Yields a point that is the $t$th fraction between $p$ + and~$q$, that is, $p + t(q-p)$. For $t=1/2$ this is the middle of + $p$ and $q$. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{2cm}{2cm}} + \pgfusepath{stroke} + \foreach \t in {0,0.25,...,1.25} + {\pgftext[at= + \pgfpointlineattime{\t}{\pgfpointorigin}{\pgfpoint{2cm}{2cm}}]{\t}} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpointlineatdistance\marg{distance}\marg{start point}\marg{end point}} + Yields a point that is located \meta{distance} many units removed + from the start point in the direction of the end point. In other + words, this is the point that results if we travel \meta{distance} + steps from \meta{start point} towards \meta{end point}. + \example +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} + \foreach \d in {0pt,20pt,40pt,70pt} + {\pgftext[at= + \pgfpointlineatdistance{\d}{\pgfpointorigin}{\pgfpoint{3cm}{2cm}}]{\d}} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpointcurveattime\marg{time $t$}\marg{point + $p$}\marg{point $s_1$}\marg{point $s_2$}\marg{point $q$}} + Yields a point that is on the Bézier curve from $p$ to $q$ with the + support points $s_1$ and $s_2$. The time $t$ is used to determine + the location, where $t=0$ yields $p$ and $t=1$ yields $q$. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{0cm}{2cm}}{\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} + \foreach \t in {0,0.25,0.5,0.75,1} + {\pgftext[at=\pgfpointcurveattime{\t}{\pgfpointorigin} + {\pgfpoint{0cm}{2cm}} + {\pgfpoint{0cm}{2cm}} + {\pgfpoint{3cm}{2cm}}]{\t}} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\subsubsection{Points on Borders of Objects} + +The following commands are useful for specifying a point that lies on +the border of special shapes. They are used, for example, by the shape +mechanism to determine border points of shapes. + +\begin{command}{\pgfpointborderrectangle\marg{direction point}\marg{corner}} + This command returns a point that lies on the intersection of a line + starting at the origin and going towards the point \meta{direction + point} and a rectangle whose center is in the origin and whose + upper right corner is at \meta{corner}. + + The \meta{direction point} should have length ``about 1pt,'' but it + will be normalized automatically. Nevertheless, the ``nearer'' the + length is to 1pt, the less rounding errors. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (2,1.5); + \pgfpathrectanglecorners{\pgfpoint{-1cm}{-1.25cm}}{\pgfpoint{1cm}{1.25cm}} + \pgfusepath{stroke} + + \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt} + \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt} + \pgfusepath{fill} + \color{red} + \pgfpathcircle{\pgfpointborderrectangle + {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfpathcircle{\pgfpointborderrectangle + {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfpointborderellipse\marg{direction point}\marg{corner}} + This command works like the corresponding command for rectangles, + only this time the \meta{corner} is the corner of the bounding + rectangle of an ellipse. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (2,1.5); + \pgfpathellipse{\pgfpointorigin}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{1.25cm}} + \pgfusepath{stroke} + + \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt} + \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt} + \pgfusepath{fill} + \color{red} + \pgfpathcircle{\pgfpointborderellipse + {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfpathcircle{\pgfpointborderellipse + {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\subsubsection{Points on the Intersection of Lines} + + +\begin{command}{\pgfpointintersectionoflines\marg{$p$}\marg{$q$}\marg{$s$}\marg{$t$}} + This command returns the intersection of a line going through $p$ + and $q$ and a line going through $s$ and $t$. If the lines do not + intersection, an arithmetic overflow will occur. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (2,2); + \draw (.5,0) -- (2,2); + \draw (1,2) -- (2,0); + \pgfpathcircle{% + \pgfpointintersectionoflines + {\pgfpointxy{.5}{0}}{\pgfpointxy{2}{2}} + {\pgfpointxy{1}{2}}{\pgfpointxy{2}{0}}} + {2pt} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\subsection{Extracting Coordinates} + +There are two commands that can be used to ``extract'' the $x$- or +$y$-coordinate of a coordinate. + +\begin{command}{\pgfextractx\marg{dimension}\marg{point}} + Sets the \TeX-\meta{dimension} to the $x$-coordinate of the point. + +\begin{codeexample}[code only] +\newdimen\mydim +\pgfextractx{\mydim}{\pgfpoint{2cm}{4pt}} +%% \mydim is now 2cm +\end{codeexample} +\end{command} + +\begin{command}{\pgfextracty\marg{dimension}\marg{point}} + Like |\pgfextractx|, except for the $y$-coordinate. +\end{command} + + + + +\subsection{Internals of How Point Commands Work} + +As a normal user of \pgfname\ you do not need to read this section. It +is relevant only if you need to understand how the point commands work +internally. + +When a command like |\pgfpoint{1cm}{2pt}| is called, all that happens +is that the two \TeX-dimension variables |\pgf@x| and |\pgf@y| are set +to |1cm| and |2pt|, respectively. A command like |\pgfpathmoveto| that +takes a coordinate as parameter will just execute this parameter and +then use the values of |\pgf@x| and |\pgf@y| as the coordinates to +which it will move the pen on the current path. + +since commands like |\pgfpointnormalised| modify other variables +besides |\pgf@x| and |\pgf@y| during the computation of the final values of +|\pgf@x| and |\pgf@y|, it is a good idea to enclose a call of a +command like |\pgfpoint| in a \TeX-scope and then make the changes of +|\pgf@x| and |\pgf@y| global as in the following example: +\begin{codeexample}[code only] +... +{ % open scope + \pgfpointnormalised{\pgfpoint{1cm}{1cm}} + \global\pgf@x=\pgf@x % make the change of \pgf@x persist past the scope + \global\pgf@y=\pgf@y % make the change of \pgf@y persist past the scope +} +% \pgf@x and \pgf@y are now set correctly, all other variables are +% unchanged +\end{codeexample} + +\makeatletter +Since this situation arises very often, the macro |\pgf@process| can +be used to perform the above code: +\begin{command}{\pgf@process\marg{code}} + Executes the \meta{code} in a scope and then makes |\pgf@x| and + |\pgf@y| global. +\end{command} + +Note that this macro is used often internally. For this reason, it is +not a good idea to keep anything important in the variables |\pgf@x| +and |\pgf@y| since they will be overwritten and changed +frequently. Instead, intermediate values can ge stored in the +\TeX-dimensions |\pgf@xa|, |\pgf@xb|, |\pgf@xc| and their +|y|-counterparts |\pgf@ya|, |\pgf@yb|, |pgf@yc|. For example, here is +the code of the command |\pgfpointadd|: +\begin{codeexample}[code only] +\def\pgfpointadd#1#2{% + \pgf@process{#1}% + \pgf@xa=\pgf@x% + \pgf@ya=\pgf@y% + \pgf@process{#2}% + \advance\pgf@x by\pgf@xa% + \advance\pgf@y by\pgf@ya} +\end{codeexample} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-quick.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-quick.tex new file mode 100644 index 00000000000..8f773b5df24 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-quick.tex @@ -0,0 +1,166 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Quick Commands} + +This section explains the ``quick'' commands of \pgfname. These +commands are executed more quickly than the normal commands of +\pgfname, but offer less functionality. You should use these commands +only if you either have a very large number of commands that need to +be processed or if you expect your commands to be executed very often. + + + +\subsection{Quick Path Construction Commands} + +The difference between the quick and the normal path commands is that +the quick path commands +\begin{itemize} +\item + do not keep track of the bounding boxes, +\item + do not allow you to arc corners, +\item + do not apply coordinate transformations. +\end{itemize} + +However, they do use the soft-path subsystem (see +Section~\ref{section-soft-paths} for details), which allows you to mix +quick and normal path commands arbitrarily. + +All quick path construction commands start with |\pgfpathq|. + +\begin{command}{\pgfpathqmoveto\marg{x dimension}\marg{y dimension}} + Either starts a path or starts a new part of a path at the coordinate + $(\meta{x dimension},\meta{y dimension})$. The coordinate is + \emph{not} transformed by the current coordinate transformation + matrix. However, any low-level transformations apply. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformxshift{1cm} + \pgfpathqmoveto{0pt}{0pt} % not transformed + \pgfpathqlineto{1cm}{1cm} % not transformed + \pgfpathlineto{\pgfpoint{2cm}{0cm}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpathqlineto\marg{x dimension}\marg{y dimension}} + The quick version of the line-to operation. +\end{command} + +\begin{command}{\pgfpathqcurveto\marg{$s^1_x$}\marg{$s^1_y$}\marg{$s^2_x$}\marg{$s^2_y$}\marg{$t_x$}\marg{$t_y$}} + The quick version of the curve-to operation. The first support point + is $(s^1_x,s^1_y)$, the second support point is $(s^2_x,s^2_y)$, + and the target is $(t_x,t_y)$. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathqmoveto{0pt}{0pt} + \pgfpathqcurveto{1cm}{1cm}{2cm}{1cm}{3cm}{0cm} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpathqcircle\marg{radius}} + Adds a radius around the origin of the given \meta{radius}. This + command is orders of magnitude faster than + |\pgfcircle{\pgfpointorigin}{|\meta{radius}|}|. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (1,1); + \pgfpathqcircle{10pt} + \pgfsetfillcolor{examplefill} + \pgfusepath{stroke,fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + + + +\subsection{Quick Path Usage Commands} + +The quick path usage commands perform similar tasks as |\pgfusepath|, +but they +\begin{itemize} +\item + do not add arrows, +\item + do not modify the path in any way, in particular, +\item + ends are not shortened, +\item + corners are not replaced by arcs. +\end{itemize} + +Note that you \emph{have to} use the quick versions in the code of +arrow tip definitions since, inside these definition, you obviously do +not want arrows to be drawn. + +\begin{command}{\pgfusepathqstroke} + Strokes the path without further ado. No arrows are drawn, no + corners are arced. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathqcircle{5pt} + \pgfusepathqstroke +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfusepathqfill} + Fills the path without further ado. +\end{command} + +\begin{command}{\pgfusepathqfillstroke} + Fills and then strokes the path without further ado. +\end{command} + +\begin{command}{\pgfusepathqclip} + Clips all subsequent drawings against the current path. The path is + not processed. +\end{command} + + +\subsection{Quick Text Box Commands} + +\begin{command}{\pgfqbox\marg{box number}} + This command inserts a \TeX\ box into a |{pgfpicture}| by + ``escaping'' to \TeX, inserting the box number \meta{box number} at + the origin, and then returning to the typesetting the picture. +\end{command} + +\begin{command}{\pgfqboxsynced\marg{box number}} + This command works similarly to the |\pgfqbox| command. However, + before inserting the text in \meta{box number}, the current + coordinate transformation matrix is applied to the current canvas + transformation matrix (is it ``synced'' with this matrix, hence the + name). + + Thus, this command basically has the same effect as if you first + called |\pgflowlevelsynccm| followed by |\pgfqbox|. However, this + command will use |\hskip| and |\raise| commands for the + ``translational part'' of the coordinate transformation matrix, + instead of adding the translational part to the current + canvas transformation matrix directly. Both methods have the same + effect (box \meta{box number} is translated where it should), but + the method used by |\pgfqboxsynced| ensures that hyperlinks are + placed correctly. Note that scaling and rotation will not (cannot, + even) apply to hyperlinks. +\end{command} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex new file mode 100644 index 00000000000..c527b42415e --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex @@ -0,0 +1,601 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section[Hierarchical Structures: Package, Environments, Scopes, and Text] +{Hierarchical Structures:\\ + Package, Environments, Scopes, and Text} + + +\subsection{Overview} + +\pgfname\ uses two kinds of hierarchical structuring: First, the +package itself is structured hierarchically, consisting of different +packages that are built on top of each other. Second, \pgfname\ allows you +to structure your graphics hierarchically using environments and scopes. + +\subsubsection{The Hierarchical Structure of the Package} + +The \pgfname\ system consists of several layers: + +\begin{description} +\item[System layer.] + The lowest layer is called the \emph{system layer}, though it might + also be called ``driver layer'' or perhaps ``backend layer.'' Its + job is to provide an abstraction of the details of which driver + is used to transform the |.dvi| file. The system layer is + implemented by the package |pgfsys|, which will load appropriate + driver files as needed. + + The system layer is documented in Part~\ref{part-system}. +\item[Basic layer.] + The basic layer is loaded by the package |pgf|. Some + applications do not need all of the functionality of the basic + layer, so it is possible to load only the |pgfcore| and some other + packages starting with |pgfbase|. + + The basic layer is documented in the present part. +\item[Frontend layer.] + The frontend layer is not loaded by a single packages. Rather, + different packages, like \tikzname\ or \textsc{pgfpict2e}, are + different frontends to the basic layer. + + The \tikzname\ frontend is documented in Part~\ref{part-tikz}. +\end{description} + +Each layer will automatically load the necessary files of the layers below +it. + +In addition to the packages of these layers, there are also some +library packages. These packages provide additional definitions of +things like new arrow tips or new plot handlers. + +The library packages are documented in Part~\ref{part-libraries}. + + + + +\subsubsection{The Hierarchical Structure of Graphics} + +Graphics in \pgfname\ are typically structured +hierarchically. Hierarchical structuring can be used to identify +groups of graphical elements that are to be treated ``in the same +way.'' For example, you might group together a number of paths, all of +which are to be drawn in red. Then, when you decide later on that you +like them to be drawn in, say, blue, all you have to do is to change +the color once. + +The general mechanism underlying hierarchical structuring is known as +\emph{scoping} in computer science. The idea is that all changes to +the general ``state'' of the graphic that are done inside a scope are +local to that scope. So, if you change the color inside a scope, this +does not affect the color used outside the scope. Likewise, when you +change the line width in a scope, the line width outside is not +changed, and so on. + +There are different ways of starting and ending scopes of graphic +parameters. Unfortunately, these scopes are sometimes ``in conflict'' +with each other and it is sometimes not immediately clear which scopes +apply. In essence, the following scoping mechanisms are available: + +\begin{enumerate} +\item + The ``outermost'' scope supported by \pgfname\ is the |{pgfpicture}| + environment. All changes to the graphic state done inside a + |{pgfpicture}| are local to that picture. + + In general, it is \emph{not} possible to set graphic parameters + globally outside any |{pgfpicture}| environments. Thus, you can + \emph{not} say |\pgfsetlinewidth{1pt}| at the beginning of your + document to have a default line width of one point. Rather, you have + to (re)set all graphic parameters inside each |{pgfpicture}|. (If + this is too bothersome, try defining some macro that does the job + for you.) +\item + Inside a |{pgfpicture}| you can use a |{pgfscope}| environment to + keep changes of the graphic state local to that environment. + + The effect of commands that change the graphic state are local to + the current |{pgfscope}| but not always to the current \TeX\ + group. Thus, if you open a \TeX\ group (some text in curly braces) + inside a |{pgfscope}|, and if you change, for example, the dash + pattern, the effect of this changed dash pattern will persist till + the end of the |{pgfscope}|. + + Unfortunately, this is not always the case. \emph{Some} graphic + parameters only persist till the end of the current \TeX\ group. For + example, when you use |\pgfsetarrows| to set the arrow tip + inside a \TeX\ group, the effect lasts only till the end of the + current \TeX\ group. +\item + Some graphic parameters are not scoped by |{pgfscope}| but + ``already'' by \TeX\ groups. For example, the effect of coordinate + transformation commands is always local to the current \TeX\ + group. + + Since every |{pgfscope}| automatically creates a \TeX\ group, all + graphic parameters that are local to the current \TeX\ group are + also local to the current |{pgfscope}|. +\item + Some graphic parameters can only be scoped using \TeX\ groups, since + in some situations it is not possible to introduce a + |{pgfscope}|. For example, a path always has to be completely + constructed and used in the same |{pgfscope}|. However, we might + wish to have different coordinate transformations apply to different + points on the path. In this case, we can use \TeX\ groups to keep + the effect local, but we could not use |{pgfscope}|. +\item + The |\pgftext| command can be used to create a scope in which \TeX\ + ``escapes back'' to normal \TeX\ mode. The text passed to the + |\pgftext| is ``heavily guarded'' against having any effect on the + scope in which it is used. For example, it is possibly to use + another |{pgfpicture}| environment inside the argument of + |\pgftext|. +\end{enumerate} + + +Most of the complications can be avoided if you stick to the following +rules: + +\begin{itemize} +\item + Give graphic commands only inside |{pgfpicture}| environments. +\item + Use |{pgfscope}| to structure graphics. +\item + Do not use \TeX\ groups inside graphics, \emph{except} for keeping + the effect of coordinate transformations local. +\end{itemize} + + + +\subsection{The Hierarchical Structure of the Package} + +Before we come to the structuring commands provided by \pgfname\ to +structure your graphics, let us first have a look at the structure of +the package itself. + +\subsubsection{The Main Package} + +To use \pgfname, include the following package: + +\begin{package}{pgf} + This package loads the complete ``basic layer'' of \pgfname. That + is, it will load all of the commands described in the current part + of this manual, but it will not load frontends like \tikzname. + + In detail, this package will load the following packages, each of + which can also be loaded individually: + \begin{itemize} + \item + |pgfsys|, which is the lowest layer of \pgfname\ and which is + always needed. This file will read |pgf.cfg| to discern which + driver is to be used. See Section~\ref{section-pgfsys} for + details. + \item + |pgfcore|, which is the central core of \pgfname\ and which is + always needed unless you intend to write a new basic layer from + scratch. + \item + |pgfbaseimage|, which provides commands for declaring and + using images. An example is |\pgfuseimage|. + \item + |pgfbaseshapes|, which provides commands for declaring and using + shapes. An example is |\pgfdeclareshape|. + \item + |pgfbaseplot|, which provides commands for plotting functions. + \end{itemize} + + Including any of the last three packages will automatically load the + first two. +\end{package} + +In \LaTeX, the package takes two options: +\begin{packageoption}{draft} + When this option is set, all images will be replaced by empty + rectangles. This can speedup compilation. +\end{packageoption} + +\begin{packageoption}{version=\meta{version}} + Indicates that the commands of version \meta{version} need to be + defined. If you set \meta{version} to |0.65|, then a large bunch of + ``compatibility commands'' are loaded. If you set \meta{version} to + |0.96|, then these compatibility commands will not be loaded. + + If this option is not given at all, then the commands of all + versions are defined. +\end{packageoption} + + +\subsubsection{The Core Package} + +\begin{package}{pgfcore} + This package defines all of the basic layer's commands, except for + the commands defined in the additional packages like + |pgfbaseplot|. Typically commands defined by the core include + |\pgfusepath| or |\pgfpoint|. The core is internally structured + into several subpackages, but the subpackages cannot be loaded + individually since they are all ``interrelated.'' +\end{package} + + +\subsubsection{The Optional Basic Layer Packages} + +The |pgf| package automatically loads the following packages, but you +can also load them individually (all of them automatically include the +core): + +\begin{itemize} + \item |pgfbaseshapes| + This package provides commands for drawing nodes and shapes. These + commands are explained in Section~\ref{section-shapes}. + + \item |pgfbaseplot| + This package provides commands for plotting function. The + commands are explained in Section~\ref{section-plots}. + + \item |pgfbaseimage| + This package provides commands for including (external) images. The + commands are explained in Section~\ref{section-images}. +\end{itemize} + + + + + +\subsection{The Hierarchical Structure of the Graphics} + +\subsubsection{The Main Environment} + + +Most, but not all, commands of the \pgfname\ package must be given +within a |{pgfpicture}| environment. The only commands that (must) be +given outside are commands having to do with including images (like +|\pgfuseimage|) and with inserting complete shadings (like +|\pgfuseshading|). However, just to keep life entertaining, the +|\pgfshadepath| command must be given \emph{inside} a |{pgfpicture}| +environment. + +\begin{environment}{{pgfpicture}} + This environment will insert a \TeX\ box containing the graphic drawn by + the \meta{environment contents} at the current position. + + \medskip + \textbf{The size of the bounding box.} + The size of the box is determined in the following + manner: While \pgfname\ parses the \meta{environment contents}, it + keeps track of a bounding box for the graphic. Essentially, this + bounding box is the smallest box that contains all coordinates + mentioned in the graphics. Some coordinates may be ``mentioned'' by + \pgfname\ itself; for example, when you add circle to the current + path, the support points of the curve making up the circle are also + ``mentioned'' despite the fact that you will not ``see'' them in + your code. + + Once the \meta{environment contents} has been parsed completely, a + \TeX\ box is created whose size is the size of the computed bounding + box and this box is inserted at the current position. + +\begin{codeexample}[] +Hello \begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}} + \pgfusepath{stroke} +\end{pgfpicture} World! +\end{codeexample} + + Sometimes, you may need more fine-grained control over the size of + the bounding box. For example, the computed bounding box may be too + large or you intensionally wish the box to be ``too small.'' In + these cases, you can use the command + |\pgfusepath{use as bounding box}|, as described in + Section~\ref{section-using-bb}. + + + \medskip + \textbf{The baseline of the bounding box.} + When the box containing the graphic is inserted into the normal + text, the baseline of the graphic is normally at the bottom of the + graphic. For this reason, the following two sets of code lines have + the same effect, despite the fact that the second graphic uses + ``higher'' coordinates than the first: + +\begin{codeexample}[] +Rectangles \begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}} + \pgfusepath{stroke} +\end{pgfpicture} and \begin{pgfpicture} + \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}} + \pgfusepath{stroke} +\end{pgfpicture}. +\end{codeexample} + + You can change the baseline using the |\pgfsetbaseline| command, see + below. + +\begin{codeexample}[] +Rectangles \begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}} + \pgfusepath{stroke} + \pgfsetbaseline{0pt} +\end{pgfpicture} and \begin{pgfpicture} + \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}} + \pgfusepath{stroke} + \pgfsetbaseline{0pt} +\end{pgfpicture}. +\end{codeexample} + + \medskip + \textbf{Including text and images in a picture.} + You cannot directly include text and images in a picture. Thus, you + should \emph{not} simply write some text in a |{pgfpicture}| or use + a command like |\includegraphics| or even |\pgfimage|. In all these + cases, you need to place the text inside a |\pgftext| command. This + will ``escape back'' to normal \TeX\ mode, see + Section~\ref{section-text-command} for details. +\end{environment} + +\begin{plainenvironment}{{pgfpicture}} + The plain \TeX\ version of the environment. Note that in this + version, also, a \TeX\ group is created around the environment. +\end{plainenvironment} + +\makeatletter +\begin{command}{\pgfsetbaseline\marg{dimension}} + This command specifies a $y$-coordinate of the picture that should + be used as the baseline of the whole picture. When a \pgfname\ + picture has been typeset completely, \pgfname\ must decide at which + height the baseline of the picture should lie. Normally, the + baseline is set to the $y$-coordinate of the bottom of the picture, + but it is often desirable to use another height. + +\begin{codeexample}[] +Text \tikz{\pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}}, + \tikz{\pgfsetbaseline{0pt} + \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}}, + \tikz{\pgfsetbaseline{.5ex} + \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}}, + \tikz{\pgfsetbaseline{-1ex} + \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}}. +\end{codeexample} +\end{command} + +\subsubsection{Graphic Scope Environments} + +Inside a |{pgfpicture}| environment you can substructure your picture +using the following environment: + +\begin{environment}{{pgfscope}} + All changes to the graphic state done inside this environment are + local to the environment. The graphic state includes the following: + \begin{itemize} + \item + The line width. + \item + The stroke and fill colors. + \item + The dash pattern. + \item + The line join and cap. + \item + The miter limit. + \item + The canvas transformation matrix. + \item + The clipping path. + \end{itemize} + Other parameters may also influence how graphics are rendered, but they + are \emph{not} part of the graphic state. For example, the arrow tip + kind is not part of the graphic state and the effect of commands + setting the arrow tip kind are local to the current \TeX\ group, not + to the current |{pgfscope}|. However, since |{pgfscope}| starts and + ends a \TeX\ group automatically, a |{pgfscope}| can be used to + limit the effect of, say, commands that set the arrow tip kind. + +\begin{codeexample}[] +\begin{pgfpicture} + \begin{pgfscope} + { + \pgfsetlinewidth{2pt} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{2ex}} + \pgfusepath{stroke} + } + \pgfpathrectangle{\pgfpoint{3ex}{0ex}}{\pgfpoint{2ex}{2ex}} + \pgfusepath{stroke} + \end{pgfscope} + \pgfpathrectangle{\pgfpoint{6ex}{0ex}}{\pgfpoint{2ex}{2ex}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{pgfpicture} + \begin{pgfscope} + { + \pgfsetarrows{-to} + \pgfpathmoveto{\pgfpointorigin}\pgfpathlineto{\pgfpoint{2ex}{2ex}} + \pgfusepath{stroke} + } + \pgfpathmoveto{\pgfpoint{3ex}{0ex}}\pgfpathlineto{\pgfpoint{5ex}{2ex}} + \pgfusepath{stroke} + \end{pgfscope} + \pgfpathmoveto{\pgfpoint{6ex}{0ex}}\pgfpathlineto{\pgfpoint{8ex}{2ex}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + + At the start of the scope, the current path must be empty, that is, + you cannot open a scope while constructing a path. + + It is usually a good idea \emph{not} to introduce \TeX\ groups + inside a |{pgfscope}| environment. +\end{environment} + +\begin{plainenvironment}{{pgfscope}} + Plain \TeX\ version of the |{pgfscope}| environment. +\end{plainenvironment} + + +The following scopes also encapsulate certain properties of the +graphic state. However, they are typically not used directly by the +user. + +\begin{environment}{{pgfinterruptpath}} + This environment can be used to temporarily interrupt the + construction of the current path. The effect will be that the path + currently under construction will be ``stored away'' and restored at + the end of the environment. Inside the environment you can construct + a new path and do something with it. + + An example application of this environment is the arrow tip + caching. Suppose you ask \pgfname\ to use a specific arrow tip + kind. When the arrow tip needs to be rendered for the first time, + \pgfname\ will ``cache'' the path that makes up the arrow tip. To do + so, it interrupts the current path construction and then protocols + the path of the arrow tip. The |{pgfinterruptpath}| environment is + used to ensure that this does not interfere with the path to which + the arrow tips should be attached. + + This command does \emph{not} install a |{pgfscope}|. In particular, + it does not call any |\pgfsys@| commands at all, which would, + indeed, be dangerous in the middle of a path construction. +\end{environment} + +\begin{environment}{{pgfinterruptpicture}} + This environment can be used to temporarily interrupt a + |{pgfpicture}|. However, the environment is intended only to be used + at the beginning and end of a box that is (later) inserted into a + |{pgfpicture}| using |\pgfqbox|. You cannot use this environment + directly inside a |{pgfpicture}|. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathmoveto{\pgfpoint{0cm}{0cm}} % In the middle of path, now + \newbox\mybox + \setbox\mybox=\hbox{ + \begin{pgfinterruptpicture} + Sub-\begin{pgfpicture} % a subpicture + \pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} + \end{pgfpicture}-picture. + \end{pgfinterruptpicture} + } + \pgfqbox{\mybox}% + \pgfpathlineto{\pgfpoint{0cm}{1cm}} + \pgfusepath{stroke} +\end{pgfpicture}\hskip3.9cm +\end{codeexample} +\end{environment} + + +\subsubsection{Inserting Text and Images} + +\label{section-text-command} + +Often, you may wish to add normal \TeX\ text at a certain point inside +a |{pgfpicture}|. You cannot do so ``directly,'' that is, you cannot +simply write this text inside the |{pgfpicture}| environment. Rather, +you must pass the text as an argument to the |\pgftext| command. + +You must \emph{also} use the |\pgftext| command to insert an image or +a shading into a |{pgfpicture}|. + +\begin{command}{\pgftext\opt{\oarg{options}}\marg{text}} + This command will typeset \meta{text} in normal \TeX\ mode and + insert the resulting box into the |{pgfpicture}|. The bounding box + of the graphic will be updated so that all of the text box is + inside. Be default, the text box is centered at the origin, but this + can be changed either by giving appropriate \meta{options} or by + applying an appropriate coordinate transformation beforehand. + + The \meta{text} may contain verbatim text. (In other words, the + \meta{text} ``argument'' is not a normal argument, but is put in a + box and some |\aftergroup| hackery is used to find the end of the + box.) + + \pgfname's current (high-level) coordinate transformation is + synchronized with the canvas transformation matrix temporarily + when the text box is inserted. The effect is that if there is + currently a high-level rotation of, say, 30 degrees, the \meta{text} + will also be rotated by thirty degrees. If you do not want this + effect, you have to (possibly temporarily) reset the high-level + transformation matrix. + + The following \meta{options} may be given as conveniences: + \begin{itemize} + \itemoption{left} + causes the text box to be placed such that its left border is on the origin. +\begin{codeexample}[] +\tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[left] {lovely}} +\end{codeexample} + \itemoption{right} + causes the text box to be placed such that its right border is on the origin. +\begin{codeexample}[] +\tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[right] {lovely}} +\end{codeexample} + \itemoption{top} + causes the text box to be placed such that its top is on the + origin. This option can be used together with the |left| or + |right| option. +\begin{codeexample}[] +\tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[top] {lovely}} +\end{codeexample} +\begin{codeexample}[] +\tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[top,right] {lovely}} +\end{codeexample} + \itemoption{bottom} + causes the text box to be placed such that its bottom is on the + origin. +\begin{codeexample}[] +\tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[bottom] {lovely}} +\end{codeexample} +\begin{codeexample}[] +\tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[bottom,right] {lovely}} +\end{codeexample} + \itemoption{base} + causes the text box to be placed such that its baseline is on the + origin. +\begin{codeexample}[] +\tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base] {lovely}} +\end{codeexample} +\begin{codeexample}[] +\tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,right] {lovely}} +\end{codeexample} + \itemoption{at}|=|\meta{point} + Translates the origin (that is, the point where the text is + shown) to \meta{point}. +\begin{codeexample}[] +\tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,at={\pgfpoint{1cm}{0cm}}] {lovely}} +\end{codeexample} + \itemoption{x}|=|\meta{dimension} + Translates the origin by \meta{dimension} along the $x$-axis. +\begin{codeexample}[] +\tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,x=1cm,y=-0.5cm] {lovely}} +\end{codeexample} + \itemoption{y}|=|\meta{dimension} + works like the |x| option. + \itemoption{rotate}|=|\meta{degree} + Rotates the coordinate system by \meta{degree}. This will also + rotate the text box. +\begin{codeexample}[] +\tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,x=1cm,y=-0.5cm,rotate=30] {lovely}} +\end{codeexample} + \end{itemize} + +\end{command} + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex new file mode 100644 index 00000000000..873d9a823ff --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex @@ -0,0 +1,326 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Declaring and Using Shadings} + +\label{section-shadings} + +\subsection{Overview} + +A shading is an area in which the color changes smoothly between different +colors. Similarly to an image, a shading must first be declared before +it can be used. Also similarly to an image, a shading is put into a +\TeX-box. Hence, in order to include a shading in a |{pgfpicture}|, +you have to use |\pgftext| around it. + +There are three kinds of shadings: horizontal, vertical, and radial +shadings. However, you can rotate and clip shadings like any other +graphics object, which allows you to create more complicated +shadings. Horizontal shadings could be created by rotating a vertical +shading by 90 degrees, but explicit commands for creating both +horizontal and vertical shadings are included for convenience. + +Once you have declared a shading, you can insert it into text using +the command |\pgfuseshading|. This command cannot be used directly in +a |{pgfpicture}|, you have to put a |\pgftext| around it. The second +command for using shadings, |\pgfshadepath|, on the other hand, can +only be used inside |{pgfpicture}| environments. It will ``fill'' the +current path with the shading. + +A horizontal shading is a horizontal bar of a certain height whose +color changes smoothly. You must at least specify the colors at the +left and at the right end of the bar, but you can also add color +specifications for points in between. For example, suppose you +which to create a bar that is red at the left end, green in the +middle, and blue at the end. Suppose you would like the bar to be 4cm +long. This could be specified as follows: +\begin{codeexample}[code only] +rgb(0cm)=(1,0,0); rgb(2cm)=(0,1,0); rgb(4cm)=(0,0,1) +\end{codeexample} +This line means that at 0cm (the left end) of the bar, the color +should be red, which has red-green-blue (rgb) components (1,0,0). At +2cm, the bar should be green, and at 4cm it should be blue. +Instead of |rgb|, you can currently also specify |gray| as +color model, in which case only one value is needed, or |color|, +in which case you must provide the name of a color in parentheses. In +a color specification the individual specifications must +be separated using a semicolon, which may be followed by a whitespace +(like a space or a newline). Individual specifications must be given +in increasing order. + +\subsection{Declaring Shadings} + +\begin{command}{\pgfdeclarehorizontalshading\oarg{color list}\marg{shading + name}\marg{shading height}\marg{color specification}} + Declares a horizontal shading named \meta{shading name} of the specified + \meta{height} with the specified colors. The length of the bar is + deduced automatically from the maximum dimension in the specification. + +\begin{codeexample}[] +\pgfdeclarehorizontalshading{myshadingA} + {1cm}{rgb(0cm)=(1,0,0); color(2cm)=(green); color(4cm)=(blue)} +\pgfuseshading{myshadingA} +\end{codeexample} + + The effect of the \meta{color list}, which is a + comma-separated list of colors, is the following: Normally, when + this list is empty, once a shading has been declared, it becomes + ``frozen.'' This means that even if you change a color that was used + in the declaration of the shading later on, the shading will not + change. By specifying a \meta{color list} you can specify + that the shading should be recalculated whenever one of the colors + listed in the list changes (this includes effects like color + mixins). Thus, when you specify a \meta{color list}, + whenever the shading is used, \pgfname\ first converts the colors in the + list to \textsc{rgb} triples using the current values of the + colors and taking any mixins and blends into account. If the + resulting \textsc{rgb} triples have not yet been used, a new + shading is internally created and used. Note that if the + option \meta{color list} is used, then no shading is created until + the first use of |\pgfuseshading|. In particular, the colors + mentioned in the shading need not be defined when the declaration is + given. + + When a shading is recalculated because of a change in the + colors mentioned in \meta{color list}, the complete shading + is recalculated. Thus even colors not mentioned in the list will be + used with their current values, not with the values they had upon + declaration. + +\begin{codeexample}[] +\pgfdeclarehorizontalshading[mycolor]{myshadingB} + {1cm}{rgb(0cm)=(1,0,0); color(2cm)=(mycolor)} +\colorlet{mycolor}{green} +\pgfuseshading{myshadingB} +\colorlet{mycolor}{blue} +\pgfuseshading{myshadingB} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfdeclareverticalshading\oarg{color list}\marg{shading + name}\marg{shading width}\marg{color specification}} + Declares a vertical shading named \meta{shading name} of the + specified \meta{width}. The height of the bar is deduced + automatically. The effect of \meta{color list} is the same as for + horizontal shadings. + +\begin{codeexample}[] +\pgfdeclareverticalshading{myshadingC} + {4cm}{rgb(0cm)=(1,0,0); rgb(1.5cm)=(0,1,0); rgb(2cm)=(0,0,1)} +\pgfuseshading{myshadingC} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfdeclareradialshading\oarg{color list}\marg{shading + name}\marg{center point}\marg{color specification}} + Declares an radial shading. A radial shading is a circle whose inner + color changes as specified by the color specification. Assuming that + the center of the shading is at the origin, the color of the center + will be the color specified for 0cm and the color of the border of + the circle will be the color for the maximum dimension given in + the \meta{color specified}. This maximum will also be the radius of + the circle. If the \meta{center point} is not at the + origin, the whole shading inside the circle (whose size remains + exactly the same) will be distorted such that the given center now + has the color specified for 0cm. The effect of \meta{color list} is + the same as for horizontal shadings. + +\begin{codeexample}[] +\pgfdeclareradialshading{sphere}{\pgfpoint{0.5cm}{0.5cm}}% + {rgb(0cm)=(0.9,0,0); + rgb(0.7cm)=(0.7,0,0); + rgb(1cm)=(0.5,0,0); + rgb(1.05cm)=(1,1,1)} +\pgfuseshading{sphere} +\end{codeexample} +\end{command} + + +\subsection{Using Shadings} +\label{section-shading-a-path} + +\begin{command}{\pgfuseshading\marg{shading name}} + Inserts a previously declared shading into the text. If you wish to + use it in a |pgfpicture| environment, you should put a |\pgfbox| + around it. + +\begin{codeexample}[] +\begin{pgfpicture} + \pgfdeclareverticalshading{myshadingD} + {20pt}{color(0pt)=(red); color(20pt)=(blue)} + \pgftext[at=\pgfpoint{1cm}{0cm}] {\pgfuseshading{myshadingD}} + \pgftext[at=\pgfpoint{2cm}{0.5cm}]{\pgfuseshading{myshadingD}} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfshadepath\marg{shading name}\marg{angle}} + This command must be used inside a |{pgfpicture}| environment. The + effect is a bit complex, so let us go over it step by step. + + First, \pgfname\ will setup a local scope. + + Second, it uses the current path to clip everything inside this + scope. However, the current path is once more available after the + scope, so it can be used, for example, to stroke it. + + Now, the \meta{shading name} should be a shading whose width and + height are 100\,bp, that is, 100 big points. \pgfname\ has a look at + the bounding box of the current path. This bounding box is computed + automatically when a path is computed; however, it can sometimes be + (quite a bit) too large, especially when complicated curves are + involved. + + Inside the scope, the low-level transformation matrix is modified. + The center of the shading is translated (moved) such that it lies on + the center of the bounding box of the path. The low-level coordinate + system is also scaled such that the shading ``covers'' the shading (the + details are a bit more complex, see below). Finally, the coordinate + system is rotated by \meta{angle}. + + After everything has been set up, the shading is inserted. Due to + the transformations and clippings, the effect will be that the + shading seems to ``fill'' the path. + + If both the path and the shadings were always rectangles and if + rotation were never involved, it would be easy to scale shadings + such they always cover the path. However, when a vertical shading is + rotated, it must obviously be ``magnified'' so that it + still covers the path. Things get worse when the path is not a + rectangle itself. + + For these reasons, things work slightly differently ``in reality.'' + The shading is scaled and translated such that the + the point $(50\mathrm{bp},50\mathrm{bp})$, which is the middle of + the shading, is at the middle of the path and such that the the + point $(25\mathrm{bp},25\mathrm{bp})$ is at the lower left corner of + the path and that $(75\mathrm{bp},75\mathrm{bp})$ is at upper + right corner. + + In other words, only the center quarter of the shading will actually + ``survive the clipping'' if the path is a rectangle. If the path is + not a rectangle, but, say, a circle, even less is seen of the + shading. Here is an example that demonstrates this effect: + +\begin{codeexample}[] +\pgfdeclareverticalshading{myshadingE}{100bp} + {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} +\pgfuseshading{myshadingE} +\hskip 1cm +\begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingE}{0} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{1cm}{2cm}} + \pgfshadepath{myshadingE}{0} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{5cm}{0cm}}{\pgfpoint{2cm}{2cm}} + \pgfshadepath{myshadingE}{45} + \pgfusepath{stroke} + \pgfpathcircle{\pgfpoint{9cm}{1cm}}{1cm} + \pgfshadepath{myshadingE}{45} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + + As can be seen above in the last case, the ``hidden'' part of the + shading actually \emph{can} become visible if the shading is + rotated. The reason is that it is scaled as if no rotation took + place, then the rotation is done. + + The following graphics show which part of the shading are actually + shown: + +\begin{codeexample}[] +\pgfdeclareverticalshading{myshadingF}{100bp} + {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} +\begin{tikzpicture} + \draw (50bp,50bp) node {\pgfuseshading{myshadingF}}; + \draw[white,thick] (25bp,25bp) rectangle (75bp,75bp); + \draw (50bp,0bp) node[below] {first two applications}; + + \begin{scope}[xshift=5cm] + \draw (50bp,50bp) node{\pgfuseshading{myshadingF}}; + \draw[rotate around={45:(50bp,50bp)},white,thick] (25bp,25bp) rectangle (75bp,75bp); + \draw (50bp,0bp) node[below] {third application}; + \end{scope} + + \begin{scope}[xshift=10cm] + \draw (50bp,50bp) node{\pgfuseshading{myshadingF}}; + \draw[white,thick] (50bp,50bp) circle (25bp); + \draw (50bp,0bp) node[below] {fourth application}; + \end{scope} +\end{tikzpicture} +\end{codeexample} + + An advantage of this approach is that when you rotate a radial + shading, no distortion is introduced: + +\begin{codeexample}[] +\pgfdeclareradialshading{ballshading}{\pgfpoint{-10bp}{10bp}} + {color(0bp)=(red!15!white); color(9bp)=(red!75!white); + color(18bp)=(red!70!black); color(25bp)=(red!50!black); color(50bp)=(black)} +\pgfuseshading{ballshading} +\hskip 1cm +\begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{1cm}{1cm}} + \pgfshadepath{ballshading}{0} + \pgfusepath{} + \pgfpathcircle{\pgfpoint{3cm}{0cm}}{1cm} + \pgfshadepath{ballshading}{0} + \pgfusepath{} + \pgfpathcircle{\pgfpoint{6cm}{0cm}}{1cm} + \pgfshadepath{ballshading}{45} + \pgfusepath{} +\end{pgfpicture} +\end{codeexample} + + If you specify a rotation of $90^\circ$ + and if the path is not a square, but an elongated rectangle, the + ``desired'' effect results: The shading will exactly vary between + the colors at the 25bp and 75bp boundaries. Here is an example: + +\begin{codeexample}[] +\pgfdeclareverticalshading{myshadingG}{100bp} + {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} +\begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingG}{0} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingG}{90} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{6cm}{0cm}}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingG}{45} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + + + As a final example, let us define a ``rainbow spectrum'' shading for + use with \tikzname. +\begin{codeexample}[] +\pgfdeclareverticalshading{rainbow}{100bp} + {color(0bp)=(red); color(25bp)=(red); color(35bp)=(yellow); + color(45bp)=(green); color(55bp)=(cyan); color(65bp)=(blue); + color(75bp)=(violet); color(100bp)=(violet)} +\begin{tikzpicture}[shading=rainbow] + \shade (0,0) rectangle node[white] {\textsc{pride}} (2,1); + \shade[shading angle=90] (3,0) rectangle +(1,2); +\end{tikzpicture} +\end{codeexample} + + Note that rainbow shadings are \emph{way} to colorful in almost all + applications. +\end{command} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-snakes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-snakes.tex new file mode 100644 index 00000000000..6c23140fbe7 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-snakes.tex @@ -0,0 +1,391 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Snakes} + +\label{section-base-snakes} + +\subsection{Overview} + +A \emph{snake} is a ``way of adding a winding line to a path.'' To be +a bit more precise, you use snakes to extend the path and the +commands for using snakes start with |\pgfpath|. However, snakes do +not necessarily extend the path using line-to and curve-to operations; +rather, they can also contain move-to operations and, thereby, cause +the path to be split into many subpaths. + +As an example, let us consider a simple snake like the |zigzag| +snake. It looks like this: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[snake=zigzag] (0,0) -- (3,0); + \draw[snake=zigzag] (0,-.5) -- (3,-1); +\end{tikzpicture} +\end{codeexample} + +The above example demonstrates the two key features of snakes: +\begin{enumerate} +\item + Snakes are made up from little segments that are repeated several + times. For the |zigzag| snake these segements look like this: + \tikz{\draw[snake=zigzag] (0,0) -- (\pgfsnakesegmentlength+0.1pt,0pt);}. +\item + Snakes ``follow along a straight to the target point.'' Thus, when + the target point is not to the right of the start point, the snake + is rotated appropriately. +\end{enumerate} + + +In order to use snakes, they first have to be \emph{declared}. This +declaration contains a detailed description of how each segement of +the snake looks like and in what ordering the different possible +segments are used. + +Once a snake has been declared, it can be used. For this you specify a +target point and a snaked line will be added from the last point +current point to the target point. + + +\subsection{Declaring a Snake} + + +\subsubsection{Segments} + +When you declare a snake, you provide a description of how the +different segments of the snake will be rendered. The description of +each segment should be given in a way as if the target of the snaked +line where at $(+\infty,0)$ and as if the segment's start where at the +origin. Thus, for example, the segment of the |zigzag| might be +defined using the following code: +\begin{codeexample}[code only] +\pgfpathlineto{\pgfpoint{5pt}{5pt}} +\pgfpathlineto{\pgfpoint{15pt}{-5pt}} +\pgfpathlineto{\pgfpoint{20pt}{0pt}} +\end{codeexample} + +\pgfname\ will ensure that an appropriate coordinate transformation +is in place when the snake segment is added to the path such that +the snake segment actually points in the right direction. Also +subsequent snake segments will be transformed such that they are +``further along the line'' toward the target. All transformations +are setup automatically. + +Note that we did not use a |\pgfpathmoveto{\pgfpointorigin}| at the +beginning of the segment code. Doing so would subdivide the path into +numerous subpath. Rather, we assume that the previous segment caused +the current point to be at the origin. + +While we can now describe segments, we still need a way to ``stop'' +the snake. Also, \pgfname\ needs to know the width of the different +snake segments such that it can translate the next segment correctly. +Even though it would be possible to compute all this information +automatically, \pgfname\ does not do so and you have to provide the +information ``by hand'' for each segment. + + +\subsubsection{Snake Automata} + +Up to now our snakes only have one segment that is repeated again and +again. However, we might also like to have \emph{different} segments +and use rules to describe which segment should be used where. For +example, we might have special segments at the start and at the end. + +For snakes we use a mechanism known in computer science as +\emph{finite automata} to describe which segment is used in each part +of the snake. The idea is the following: For the first segment we +start in a special \emph{state} called the \emph{initial state}. In +this state, and also in all other state later, \pgfname\ first +computes how much space is left on the snake. That is, \pgfname\ keeps +track of the distance to the target. Attached to each state there is a +set of rules of the following form: ``If the remaining distance is +less than $x$, switch to state~$q$.'' \pgfname\ checks for each of +these rules whether it applies and, if so, immediately switches to +state~$q$. + +Only if none of the rules tell us to switch to another +state, \pgfname\ will execute the state's code. This code will add a +segment to the path. In addition to the rules there is also width +parameter attached to each state. \pgfname\ then translates the +coordinate system by this width and reduces the remaining distance. +Then, \pgfname\ either stays in the current state or switches to +another state, depending on yet another property attached of the +state. + +The whole process stops when a special state called |final| is +reached. The segment of this state is added to the path immediately +(it is often empty, though) and the process ends. + +\subsubsection{The Snake Declaration Command} + +\begin{command}{\pgfdeclaresnake\marg{name}\marg{initial + state}\marg{states}} + This command declares a new snake called \meta{name}. The + \meta{states} argument contains a description of the snake + automaton's states and the transitions between them. The + \meta{initial state} is the state in which the automaton starts. + + The \meta{states} argument should consist of |\state| commands, one + for each state of the snake automaton. The |\state| command is + defined only when the \meta{states} argument is executed. + +\begin{codeexample}[] +\pgfdeclaresnake{example snake}{initial} +{ + \state{initial}[width=10pt] + { + \pgfpathlineto{\pgfpoint{0pt}{5pt}} + \pgfpathlineto{\pgfpoint{5pt}{5pt}} + \pgfpathlineto{\pgfpoint{5pt}{-5pt}} + \pgfpathlineto{\pgfpoint{10pt}{-5pt}} + \pgfpathlineto{\pgfpoint{10pt}{0pt}} + } + \state{final} + { + \pgfpathlineto{\pgfpoint{\pgfsnakeremainingdistance}{0pt}} + } +} +\tikz{\draw[snake=example snake] (0,0) -- (3,0); + \draw[snake=example snake] (0,-1) -- (3,-3);} +\end{codeexample} + + The |\state| command works as follows: + \begin{command}{\state\marg{name}\oarg{options}\marg{code}} + This command declares a new state inside the current snake + automaton. The state is names \meta{name}. + + When \pgfname\ is in state \meta{name}, the following things + happen: + \begin{enumerate} + \item + The \meta{options} are parsed. This may lead, see below, to a + state switch. When this happens, the following steps are not + executed. The \meta{options} are executed one after the other in + the given order. If an option causes a state switch, the switch + is immediate, even if later options might cause a different + state switch. + \item + The \meta{code} is executed. When this happens, the coordinate + transformation will be setup such that the origin is at the + start of the segment and such that the target lies in the + direction ``east.'' + \item + After the \meta{code} has been executed, the state switches to + whatever state has been specified inside the \meta{options} + using the |next state| option. If no |next state| has been + specified, the state stays the same. + \end{enumerate} + + The following options are allowed inside the \meta{options}: + \begin{itemize} + \itemoption{switch if less than}|=|\meta{dimension}| to |\meta{new state} + When this option is encountered, \pgfname\ checks whether the + remaining distance to the target is less than + \meta{dimension}. If so, an immediate state switch to \meta{new + state} occurs. + \itemoption{width}|=|\meta{dimension} + This option tells \pgfname\ the width of the segment if it is + appended to the path. The coordinate system will, afterward, be + translated by \meta{dimension} to ensure that the next segment + starts where the current one ended. + + In addition, this option will cause an immediate switch to the + state |final| if the remaining distance is less than + \meta{dimension}. The effect is the same as if you had said + |switch if less than=|\meta{dimension}| to final| just before + the |width| option. + \itemoption{next state}=\meta{new state} + After the segment has been added to the path, a state switch to + \meta{new state} is performed. If this option is not given, the + next state is the same as the current state. + \end{itemize} + + There are two dimensions that are useful inside snake automata: + \begin{command}{\pgfsnakeremainingdistance} + This \TeX\ dimension holds the remaining distance to the target. + \end{command} + \begin{command}{\pgfsnakecompleteddistance} + This \TeX\ dimension holds the distance already completed on the + snake. + \end{command} + \end{command} + + As a final example we present a more complicated snake that makes + use of the different options: +\begin{codeexample}[] +\pgfdeclaresnake{complicated example snake}{initial} +{ + \state{initial}[width=5pt,next state=up] + { \pgfpathlineto{\pgfpoint{5pt}{0pt}} } + + \state{up}[width=5pt,next state=down] + { + \ifdim\pgfsnakeremainingdistance>\pgfsnakecompleteddistance + % Growing + \pgfpathlineto{\pgfpoint{0pt}{\pgfsnakecompleteddistance}} + \pgfpathlineto{\pgfpoint{5pt}{\pgfsnakecompleteddistance}} + \pgfpathlineto{\pgfpoint{5pt}{0pt}} + \else + % Shrinking + \pgfpathlineto{\pgfpoint{0pt}{\pgfsnakeremainingdistance}} + \pgfpathlineto{\pgfpoint{5pt}{\pgfsnakeremainingdistance}} + \pgfpathlineto{\pgfpoint{5pt}{0pt}} + \fi% + } + \state{down}[width=5pt,next state=up] + { + \ifdim\pgfsnakeremainingdistance>\pgfsnakecompleteddistance + % Growing + \pgfpathlineto{\pgfpoint{0pt}{-\pgfsnakecompleteddistance}} + \pgfpathlineto{\pgfpoint{5pt}{-\pgfsnakecompleteddistance}} + \pgfpathlineto{\pgfpoint{5pt}{0pt}} + \else + % Shrinking + \pgfpathlineto{\pgfpoint{0pt}{-\pgfsnakeremainingdistance}} + \pgfpathlineto{\pgfpoint{5pt}{-\pgfsnakeremainingdistance}} + \pgfpathlineto{\pgfpoint{5pt}{0pt}} + \fi% + } + \state{final} + { + \pgfpathlineto{\pgfpoint{\pgfsnakeremainingdistance}{0pt}} + } +} +\begin{tikzpicture}[snake=complicated example snake] + \draw[snake] (0,0) -- (3,0); + \fill[red!50,snake,rounded corners=2pt] (.5,-2) -- ++(2.5,-2.5) + [snake=none] -- ++(0,-.5) -| (0,-2) -- cycle; +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\subsubsection{Predefined Snakes} + +Only two very simple and basic snakes are predefined when you load +\pgfname. For more interesting snakes you can use the package +|pgflibrarysnakes|. + +\begin{snake}{lineto} + This most trivial of all snakes is simply a straight line. This + snake is typically not used in a ``stand alone'' fashion. Rather, it + is useful as a ``subsnake'' of the |\pgfsnakesto| command. +\end{snake} + +\begin{snake}{moveto} + Arguably, this snake is even simpler than the previous snake. This + snake consists of a simple move-to operation. Like the |lineto| + snake, it is useful as a ``subsnake'' of the |\pgfsnakesto| + command. +\end{snake} + + + +\subsection{Using Snakes} + +Three commands can be used to use a snake. + +\begin{command}{\pgfpathsnakealongvector\marg{snake}\marg{length}\marg{vector}} + This command will append the \meta{snake} to the current path. The + length of the snake is given by \meta{length}. The \meta{vector} + should be a normalizes vector (a vector having length |1pt|) + pointing in the direction in which the snake should grow. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpoint{1cm}{1cm}} + \pgfpathsnakealongvector{zigzag}{2cm}{\pgfpointpolar{30}{1pt}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpathsnakesto\marg{snake list}\marg{target}} + This command will append the snakes in the \meta{snake list} to the + current path such that it ends at \meta{point}. This command calls the previous + one (repeatedly, possibly) after having computed the distance from + the current point to \meta{target} and normalized the vector + connecting the current point to the target. + + The \meta{snake list} is a comma-separated list of pairs consisting + of a snake name in curly braces and a distance in curly braces. For + example, a snake list might be |{lineto}{1cm},{moveto}{2cm}|. This + is interpreted as follows: Use a |lineto| snake for the first + centimeter of the way to the \meta{target}, then use the |moveto| + snake for the next two centimeters. + + No attempt is made to check or ensure that the distances of the + ``subsnakes' add up to the distnace from the current point to the + \meta{target}. However, it is possible to refer to this distance + inside the \meta{snake list}: While the snake list is processed, the + two \TeX-dimensions |\pgfsnakeremainingdistance| and + |\pgfsnakecompleteddistance| will be set to the correct values. For + example, consider the example from a above, consisting of a |lineto| + and a |moveto| snake. Suppose the distance to \meta{target} where + 5cm. Then, when the length of the first subsnake is computed, the + remaining distance willbe set to 5cm and the completed distance to + 0cm. When the length of the second subsnake is computed, the + remaining distance wil be 4cm and the completed distance will be + 1cm. + + Here are some useful examles: |{zigzag}{\pgfsnakeremainingdistance}| + is a \meta{snake list} that consists only of a |zigzag| snake whose + length is the total distance from the current point to the + \meta{target}. Next, to get a snake that is a |zigzag| snake that is + preceeded and succeeded by 3mm of |lineto|, you can use the + following: +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines](0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathsnakesto{% + {lineto}{3mm},% + {zigzag}{\pgfsnakeremainingdistance-6mm},% + {lineto}{3mm}} + {\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + + Note that the computation of the distance may be imprecise. In + general, the placement precision of the snakes will not be perfect. +\end{command} + +\begin{command}{\pgfpathsnaketo\marg{snake}\marg{target}} + This command is just a shortcut for calling |\pgfpathsnakesto| for a + single snake whose length is |\pgfsnakeremainingdistance|. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpoint{1cm}{1cm}} + \pgfpathsnaketo{zigzag}{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +As was already mentioned, when each segment of the snake is added to +the path, an appropriate coordinate transformation will be in +force. It is sometimes useful to add an additional transformation +locally. For example, by reflecting everything around the $x$-axis +right before each segment is added, the snake will effectively be +mirrored along the path. The following command allows you to install +such a ``last minute transformation.'' + +\begin{command}{\pgfsetsnakesegmenttransformation\marg{code}} + The \meta{code} will be executed at the very beginning of each + segment. Normally, this be a transformation command that changes the + $y$-axis in some way. +\end{command} + + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "~/texmf/tex/generic/pgf/doc/pgf/version-for-pdftex/en/pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex new file mode 100644 index 00000000000..991c7edfc45 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex @@ -0,0 +1,537 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Coordinate and Canvas Transformations} + +\subsection{Overview} + +\pgfname\ offers two different ways of scaling, shifting, and rotating +(these operations are generally known as \emph{transformations}) +graphics: You can apply \emph{coordinate transformations} to all +coordinates and you can apply \emph{canvas transformations} to the +canvas on which you draw. (The names ``coordinate'' and ``canvas'' +transformations are not standard, I introduce them only for the +purposes of this manual.) + +The difference is the following: + +\begin{itemize} +\item + As the name ``coordinate transformation'' suggests, coordinate + transformations apply only to coordinates. For example, when you + specify a coordinate like |\pgfpoint{1cm}{2cm}| and you wish to + ``use'' this coordinate---for example as an argument to a + |\pgfpathmoveto| command---then the coordinate transformation matrix + is applied to the coordinate, resulting in a new + coordinate. Continuing the example, if the current coordinate + transformation is ``scale by a factor of two,'' the coordinate + |\pgfpoint{1cm}{2cm}| actually designates the point + $(2\mathrm{cm},4\mathrm{cm})$. + + Note that coordinate transformations apply \emph{only} to + coordinates. They do not apply to, say, line width or shadings or + text. +\item + The effect of a ``canvas transformation'' like ``scale by a factor + of two'' can be imagined as follows: You first draw your picture on + a ``rubber canvas'' normally. Then, once you are done, the whole + canvas is transformed, in this case stretched by a factor of + two. In the resulting image \emph{everything} will be larger: Text, + lines, coordinates, and shadings. +\end{itemize} + +In many cases, it is preferable that you use coordinate +transformations and not canvas transformations. When canvas +transformations are used, \pgfname\ looses track of the coordinates of +nodes and shapes. Also, canvas transformations often cause undesirable +effects like changing text size. For these reasons, \pgfname\ makes it +easy to setup the coordinate transformation, but a bit harder to +change the canvas transformation. + + +\subsection{Coordinate Transformations} + +\subsubsection{How PGF Keeps Track of the Coordinate Transformation + Matrix} + +\pgfname\ has an internal coordinate transformation matrix. This +matrix is applied to coordinates ``in certain situations.'' This means +that the matrix is not always applied to every coordinate ``no matter +what.'' Rather, \pgfname\ tries to be reasonably smart at when and how +this matrix should be applied. The most prominent examples are the +path construction commands, which apply the coordinate transformation +matrix to their inputs. + +The coordinate transformation matrix consists of four numbers $a$, +$b$, $c$, and $d$, and two dimensions $s$ and $t$. When the coordinate +transformation matrix is applied to a coordinate $(x,y)$ the new +coordinate $(ax+by+s,cx+dy+t)$ results. For more details on how +transformation matrices work in general, please see, for example, the +\textsc{pdf} or PostScript reference or a textbook on computer +graphics. + +The coordinate transformation matrix is equal to the identity matrix +at the beginning. More precisely, $a=1$, $b=0$, $c=0$, $d=1$, +$s=0\mathrm{pt}$, and $t=0\mathrm{pt}$. + +The different coordinate transformation commands will modify the +matrix by concatenating it with another transformation matrix. This +way the effect of applying several transformation commands will +\emph{accumulate}. + +The coordinate transformation matrix is local to the current \TeX\ +group (unlike the canvas transformation matrix, which is local to the +current |{pgfscope}|). Thus, the effect of adding a coordinate +transformation to the coordinate transformation matrix will last only +till the end of the current \TeX\ group. + + + + +\subsubsection{Commands for Relative Coordinate Transformations} + +The following commands add a basic coordinate transformation to the +current coordinate transformation matrix. For all commands, the +transformation is applied \emph{in addition} to any previous +coordinate transformations. + +\begin{command}{\pgftransformshift\marg{point}} + Shifts coordinates by \meta{point}. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformshift{\pgfpoint{1cm}{1cm}} + \draw[red] (0,0) -- (2,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgftransformxshift\marg{dimensions}} + Shifts coordinates by \meta{dimension} along the $x$-axis. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformxshift{.5cm} + \draw[red] (0,0) -- (2,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgftransformyshift\marg{dimensions}} + Like |\pgftransformxshift|, only for the $y$-axis. +\end{command} + +\begin{command}{\pgftransformscale\marg{factor}} + Scales coordinates by \meta{factor}. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformscale{.75} + \draw[red] (0,0) -- (2,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgftransformxscale\marg{factor}} + Scales coordinates by \meta{factor} in the $x$-direction. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformxscale{.75} + \draw[red] (0,0) -- (2,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgftransformyscale\marg{factor}} + Like |\pgftransformxscale|, only for the $y$-axis. +\end{command} + + +\begin{command}{\pgftransformxslant\marg{factor}} + Slants coordinates by \meta{factor} in the $x$-direction. Here, a + factor of |1| means $45^\circ$. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformxslant{.5} + \draw[red] (0,0) -- (2,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgftransformyslant\marg{factor}} + Slants coordinates by \meta{factor} in the $y$-direction. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformyslant{-1} + \draw[red] (0,0) -- (2,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} +\end{command} + + + +\begin{command}{\pgftransformrotate\marg{degrees}} + Rotates coordinates counterclockwise by \meta{degrees}. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformrotate{30} + \draw[red] (0,0) -- (2,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgftransformcm\marg{a}\marg{b}\marg{c}\marg{d}\marg{point}} + Applies the transformation matrix given by $a$, $b$, $c$, and $d$ + and the shift \meta{point} to coordinates (in addition to any + previous transformations already in force). +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformcm{1}{1}{0}{1}{\pgfpoint{.25cm}{.25cm}} + \draw[red] (0,0) -- (2,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgftransformarrow\marg{start}\marg{end}} + Shift coordinates to the end of the line going from \meta{start} + to \meta{end} with the correct rotation. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (3,1); + \pgftransformarrow{\pgfpointorigin}{\pgfpoint{3cm}{1cm}} + \pgftext{tip} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgftransformlineattime\marg{time}\marg{start}\marg{end}} + Shifts coordinates by a specific point on a line at a specific + time. The point by which the coordinate is shifted is calculated by + calling |\pgfpointlineattime|, see + Section~\ref{section-pointsattime}. + + In addition to shifting the coordinate, a rotation \emph{may} also + be applied. Whether this is the case depends on whether the \TeX\ if + |\ifpgfslopedattime| is set to true or not. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1); + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1); + \pgfslopedattimetrue + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} +\end{tikzpicture} +\end{codeexample} + + There is another \TeX\ if that influences this command. If you set + |\ifpgfresetnontranslationattime| to true, then, between + shifting the coordinate and (possibly) rotating/sloping the + coordinate, the command |\pgftransformresetnontranslations| is + called. See the description of this command for details. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformscale{1.5} + \draw (0,0) -- (2,1); + \pgfslopedattimetrue + \pgfresetnontranslationattimefalse + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformscale{1.5} + \draw (0,0) -- (2,1); + \pgfslopedattimetrue + \pgfresetnontranslationattimetrue + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgftransformcurveattime\marg{time}\marg{start}\marg{first + support}\marg{second support}\marg{end}} + Shifts coordinates by a specific point on a curve at a specific + time, see Section~\ref{section-pointsattime} once more. + + As for the line-at-time transformation command, |\ifpgfslopedattime| + decides whether an additional rotation should be applied. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) .. controls (0,2) and (1,2) .. (2,1); + \pgftransformcurveattime{.25}{\pgfpointorigin} + {\pgfpoint{0cm}{2cm}}{\pgfpoint{1cm}{2cm}}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) .. controls (0,2) and (1,2) .. (2,1); + \pgfslopedattimetrue + \pgftransformcurveattime{.25}{\pgfpointorigin} + {\pgfpoint{0cm}{2cm}}{\pgfpoint{1cm}{2cm}}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} +\end{tikzpicture} +\end{codeexample} + The value of |\ifpgfresetnontranslationsattime| is also taken into account. +\end{command} + + +{ + \let\ifpgfslopedattime=\relax + \begin{textoken}{\ifpgfslopedattime} + Decides whether the ``at time'' transformation commands also + rotate coordinates or not. + \end{textoken} +} +{ + \let\ifpgfresetnontranslationsattime=\relax + \begin{textoken}{\ifpgfresetnontranslationsattime} + Decides whether the ``at time'' transformation commands should + reset the non-translations between shifting and rotating. + \end{textoken} +} + + +\subsubsection{Commands for Absolute Coordinate Transformations} + +The coordinate transformation commands introduced up to now are always +applied in addition to any previous transformations. In contrast, the +commands presented in the following can be used to change the +transformation matrix ``absolutely.'' Note that this is, in general, +dangerous and will often produce unexpected effects. You should use +these commands only if you really know what you are doing. + +\begin{command}{\pgftransformreset} + Resets the coordinate transformation matrix to the identity + matrix. Thus, once this command is given no transformations are + applied till the end of the scope. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformrotate{30} + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformreset + \draw[red] (0,0) -- (2,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgftransformresetnontranslations} + This command sets the $a$, $b$, $c$, and $d$ part of the coordinate + transformation matrix to $a=1$, $b=0$, $c=0$, and $d=1$. However, + the current shifting of the matrix is not modified. + + The effect of this command is that any rotation/scaling/slanting is + undone in the current \TeX\ group, but the origin is not ``moved + back.'' + + This command is mostly useful directly before a |\pgftext| command + to ensure that the text is not scaled or rotated. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformscale{2} + \pgftransformrotate{30} + \pgftransformxshift{1cm} + {\color{red}\pgftext{rotated}} + \pgftransformresetnontranslations + \pgftext{shifted only} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgftransforminvert} + Replaces the coordinate transformation matrix by a coordinate + transformation matrix that ``exactly undoes the original + transformation.'' For example, if the original transformation was + ``scale by 2 and then shift right by 1cm'' the new one is ``shift + left by 1cm and then scale by $1/2$.'' + + This command will produce an error if the determinant of + the matrix is too small, that is, if the matrix is near-singular. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformrotate{30} + \draw (0,0) -- (2,1) -- (1,0); + \pgftransforminvert + \draw[red] (0,0) -- (2,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} +\end{command} + +\subsubsection{Saving and Restoring the Coordinate Transformation + Matrix} + +There are two commands for saving and restoring coordinate +transformation matrices. + +\begin{command}{\pgfgettransform\marg{macro}} + This command will (locally) define \meta{macro} to a representation + of the current coordinate transformation matrix. This matrix can + later on be reinstalled using |\pgfsettransform|. +\end{command} + + +\begin{command}{\pgfsettransform\marg{macro}} + Reinstalls a coordinate transformation matrix that was previously + saved using |\pgfgettransform|. +\end{command} + + + +\subsection{Canvas Transformations} + +The canvas transformation matrix is not managed by \pgfname, but by +the output format like \pdf\ or PostScript. All the \pgfname\ does is +to call appropriate low-level |\pgfsys@| commands to change the canvas +transformation matrix. + +Unlike coordinate transformations, canvas transformations apply to +``everything,'' including images, text, shadings, line thickness, and +so on. The idea is that a canvas transformation really stretches and +deforms the canvas after the graphic is finished. + +Unlike coordinate transformations, canvas transformations are local to +the current |{pgfscope}|, not to the current \TeX\ group. This is due +to the fact that they are managed by the backend driver, not by \TeX\ +or \pgfname. + +Unlike the coordinate transformation matrix, it is not possible to +``reset'' the canvas transformation matrix. The only way to change it +is to concatenate it with another canvas transformation matrix or to +end the current |{pgfscope}|. + +Unlike coordinate transformations, \pgfname\ does not ``keep track'' +of canvas transformations. In particular, it will not be able to +correctly save the coordinates of shapes or nodes when a canvas +transformation is used. + +\pgfname\ does not offer a whole set of special commands for modifying +the canvas transformation matrix. Instead, different commands allow +you to concatenate the canvas transformation matrix with a coordinate +transformation matrix (and there are numerous commands for specifying +a coordinate transformation, see the previous section). + +\begin{command}{\pgflowlevelsynccm} + This command concatenates the canvas transformation matrix with the + current coordinate transformation matrix. Afterward, the coordinate + transformation matrix is reset. + + The effect of this command is to ``synchronize'' the coordinate + transformation matrix and the canvas transformation matrix. All + transformations that were previously applied by the coordinate + transformations matrix are now applied by the canvas transformation + matrix. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{1pt} + \pgftransformscale{5} + \draw (0,0) -- (0.4,.2); + \pgftransformxshift{0.2cm} + \pgflowlevelsynccm + \draw[red] (0,0) -- (0.4,.2); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgflowlevel\marg{transformation code}} + This command concatenates the canvas transformation matrix with the + coordinate transformation specified by \meta{transformation code}. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{1pt} + \pgflowlevel{\pgftransformscale{5}} + \draw (0,0) -- (0.4,.2); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgflowlevelobj\marg{transformation code}\marg{code}} + This command creates a local |{pgfscope}|. Inside this scope, + |\pgflowlevel| is first called with the argument + \meta{transformation code}, then the \meta{code} is inserted. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{1pt} + \pgflowlevelobj{\pgftransformscale{5}} {\draw (0,0) -- (0.4,.2);} + \pgflowlevelobj{\pgftransformxshift{-1cm}}{\draw (0,0) -- (0.4,.2);} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{environment}{{pgflowlevelscope}\marg{transformation code}} + This environment first surrounds the \meta{environment contents} by + a |{pgfscope}|. Then it calls |\pgflowlevel| with the argument + \meta{transformation code}. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{1pt} + \begin{pgflowlevelscope}{\pgftransformscale{5}} + \draw (0,0) -- (0.4,.2); + \end{pgflowlevelscope} + \begin{pgflowlevelscope}{\pgftransformxshift{-1cm}} + \draw (0,0) -- (0.4,.2); + \end{pgflowlevelscope} +\end{tikzpicture} +\end{codeexample} +\end{environment} + + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex new file mode 100644 index 00000000000..c59ee5fbeb3 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex @@ -0,0 +1,313 @@ +% Copyright 2005 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Input and Output Formats} +\label{section-formats} + + +\TeX\ was designed to be a flexible system. This is true both for the +\emph{input} for \TeX\ as well as for the \emph{output}. The present +section explains which input formats there are and how they are +supported by \pgfname. It also explains which different output formats +can be produced. + + + +\subsection{Supported Input Formats} + +\TeX\ does not prescribe exactly how your input should be +formatted. While it is \emph{customary} that, say, an opening brace +starts a scope in \TeX, this is by no means necessary. Likewise, it is +\emph{customary} that environments start with |\begin|, but \TeX\ +could not really care less about the exact command name. + +Even though \TeX\ can be reconfigured, users can not. For this reason, +certain \emph{input formats} specify a set of commands and conventions +how input for \TeX\ should be formatted. There are currently three +``major'' formats: Donald Knuth's original |plain| \TeX\ format, +Leslie Lamport's popular \LaTeX\ format, and Hans Hangen's Con\TeX t +format. + + +\subsubsection{Using the \LaTeX\ Format} + +Using \pgfname\ and \tikzname\ with the \LaTeX\ format is easy: You +say |\usepackage{pgf}| or |\usepackage{tikz}|. Usually, that is all +you need to do, all configuration will be done automatically and +(hopefully) correctly. + +The style files used for the \LaTeX\ format reside in the subdirectory +|latex/pgf/| of the \pgfname-system. Mainly, what these files do is to +include files in the directory |generic/pgf|. For example, here is the +content of the file |latex/pgf/frontends/tikz.sty|: + +\begin{codeexample}[code only] +% Copyright 2005 by Till Tantau <tantau@users.sourceforge.net>. +% +% This program can be redistributed and/or modified under the terms +% of the GNU Public License, version 2. + +\RequirePackage{pgf,calc,pgffor,pgflibraryplothandlers,xkeyval} + +\input{tikz.code} + +\endinput +\end{codeexample} + +The files in the |generic/pgf| directory do the actual work. + + + +\subsubsection{Using the Plain \TeX\ Format} + +When using the plain \TeX\ format, you say |\input{pgf.tex}| or +|\input{tikz.tex}|. Instead of |\begin{pgfpicture}| and + |\end{pgfpicture}| you use |\pgfpicture| and |\endpicture|. + +Unlike for the \LaTeX\ format, \pgfname\ is not as good at discerning +the appropriate configuration for the plain \TeX\ format. In +particular, it can only automatically determine the correct output +format if you use |pdftex| or |tex| plus |dvips|. For all other output +formats you need to set the macro |\pgfsysdriver| to the correct +value. See the description of using output formats later on. + +\pgfname\ was originally written for use with \LaTeX\ and this shows +in a number of places. Nevertheless, the plain \TeX\ support is +reasonably good. + +Like the \LaTeX\ style files, the plain \TeX\ files like |tikz.tex| +also just include the correct |tikz.code.tex| file. + + + +\subsubsection{Using the Con\TeX t Format} + +Currently, there is no special support for the Con\TeX t +format. Rather, you have to use \pgfname\ and \tikzname\ as if you +were using the plain \TeX\ format when using Con\TeX t. This may +change in the future. + + + + + +\subsection{Supported Output Formats} +\label{section-drivers} + +An output format is a format in which \TeX\ outputs the text it has +typeset. Producing the output is (conceptually) a two-stage process: +\begin{enumerate} +\item + \TeX\ typesets your text and graphics. The result of this + typesetting is mainly a long list of letter--coordinate pairs, plus + (possibly) some ``special'' commands. This long list of pairs + is written to something called a |.dvi|-file. +\item + Some other program reads this |.dvi|-file and translates the + letter--coordinate pairs into, say, PostScript commands for placing + the given letter at the given coordinate. +\end{enumerate} + +The classical example of this process is the combination of |latex| +and |dvips|. The |latex| program (which is just the |tex| program +called with the \LaTeX-macros preinstalled) produces a |.dvi|-file as +its output. The |dvips| program takes this output and produces a +|.ps|-file (a PostScript) file. Possibly, this file is further +converted using, say, |ps2pdf|, whose name is supposed to mean +``PostScript to PDF.'' Another example of programs using this +process is the combination of |tex| and |dvipdfm|. The |dvipdfm| +program takes a |.dvi|-file as +input and translates the letter--coordinate pairs therein into +\pdf-commands, resulting in a |.pdf| file directly. Finally, the +|tex4ht| is also a program that takes a |.dvi|-file and produces an +output, this time it is a |.html| file. The programs |pdftex| and +|pdflatex| are special: They directly produce a |.pdf|-file without +the intermediate |.dvi|-stage. However, from the programmer's point of +view they behave exactly as if there where an intermediate stage. + +Normally, \TeX\ only produces letter--coordinate pairs as its +``output.'' This obviously makes is difficult tho draw, say, a +curve. For this, ``special'' commands can be used. Unfortunately, +these special commands are not the same for the different programs +that process the |.dvi|-file. Indeed, every program that takes a +|.dvi|-file as input has a totally different syntax for the special +commands. + +One of the main jobs of \pgfname\ is to ``abstract way'' the +difference in the syntax of the different programs. However, this +means that support for each program has to be ``programmed,'' which is +a time-consuming and complicated process. + + +\subsubsection{Selecting the Backend Driver} + +When \TeX\ typesets your document, it does not know which program +you are going to use to transform the |.dvi|-file. If your |.dvi|-file +does not contain any special commands, this would be fine; but these +days almost all |.dvi|-files contain lots of special commands. It is +thus necessary to tell \TeX\ which program you are going to use later +on. + +Unfortunately, there is no ``standard'' way of telling this to +\TeX. For the \LaTeX\ format a sophisticated mechanism exists inside +the |graphics| package and \pgfname\ plugs into this mechanism. For +other formats and when this plugging does not work as expected, it is +necessary to tell \pgfname\ directly which program you are going to +use. This is done by redefining the macro |\pgfsysdriver| to an +appropriate value \emph{before} you load |pgf|. If you are going to +use the |dvips| program, you set this macro to the value +|pgfsys-dvips.def|; if you use |pdftex| or |pdflatex|, you set it to +|pgfsys-pdftex.def|; and so on. In the following, details of the +support of the different programs are discussed. + + +\subsubsection{Producing PDF Output} + +\pgfname\ supports three programs that produce \pdf\ output (\pdf\ means +``portable document format'' and was invented by the Adobe company): +|dvipdfm|, |pdftex|, and |vtex|. The |pdflatex| program is the same as the +|pdftex| program: it uses a different input format, but the output is +exactly the same. + +\begin{filedescription}{pgfsys-pdftex.def} + This is the driver file for use with pdf\TeX, that is, with the + |pdftex| or |pdflatex| command. It includes + |pgfsys-common-pdf.def|. + + This driver has the ``complete'' functionality. This means, + everything \pgfname\ ``can do at all'' is implemented in this + driver. +\end{filedescription} + +\begin{filedescription}{pgfsys-dvipdfm.def} + This is a driver file for use with (|la|)|tex| followed by |dvipdfm|. It + includes |pgfsys-common-pdf.def|. + + This driver supports most of \pgfname's features, but there are some + restrictions: + \begin{enumerate} + \item + In \LaTeX\ mode it uses |graphicx| for the graphics + inclusion and does not support masking. + \item + In plain \TeX\ mode it does not support image inclusion. + \end{enumerate} +\end{filedescription} + +\begin{filedescription}{pgfsys-vtex.def} + This is the driver file for use with the commercial \textsc{vtex} + program. Even though is will produce \textsc{pdf} output, it + includes |pgfsys-common-postscript.def|. Note that the + \textsc{vtex} program can produce \emph{both} Postscript and + \textsc{pdf} output, depending on the command line + parameters. However, whether you produce Postscript or + \textsc{pdf} output does not change anything with respect to the + driver. + + This driver supports most of \pgfname's features, except for + the following restrictions: + \begin{enumerate} + \item + In \LaTeX\ mode it uses |graphicx| for the graphics + inclusion and does not support masking. + \item + In plain \TeX\ mode it does not support image inclusion. + \item + Shading is fully implemented, but yields the same quality as the + implementation for |dvips|. + \item + Opacity is not implemented at all. + \end{enumerate} +\end{filedescription} + +It is also possible to produce a |.pdf|-file by first producing a +PostScript file (see below) and then using a PostScript-to-\pdf\ +conversion program like |ps2pdf| or the Acrobat Distiller. + + +\subsubsection{Producing PostScript Output} + +\begin{filedescription}{pgfsys-dvips.def} + This is a driver file for use with (|la|)|tex| followed by + |dvips|. It includes |pgfsys-common-postscript.def|. + + This driver also supports most of \pgfname's features, except for + the following restrictions: + \begin{enumerate} + \item + In \LaTeX\ mode it uses |graphicx| for the graphics + inclusion and does not support masking. + \item + In plain \TeX\ mode it does not support image inclusion. + \item + Shading is fully implemented, but the results will not be + as good as with a driver producing |.pdf| as output. + \item + Opacity works only in conjunction with newer versions of + GhostScript. + \end{enumerate} +\end{filedescription} + +You can also use the |vtex| program together with |pgfsys-vtex.def| to +produce Postscript output. + + + +\subsubsection{Producing HTML / SVG Output} + +The |tex4ht| program converts |.dvi|-files to |.html|-files. While the +\textsc{html}-format cannot be used to draw graphics, the +\textsc{svg}-format can. Using the following driver, you can ask +\pgfname\ to produce an \textsc{svg}-picture for each \pgfname\ +graphic in your text. + +\begin{filedescription}{pgfsys-tex4ht.def} + This is a driver file for use with the |tex4ht| program. It includes + |pgfsys-common-svg.def|. + + When using this driver you should be aware of the following + restrictions: + \begin{enumerate} + \item + In \LaTeX\ mode it uses |graphicx| for the graphics + inclusion. + \item + In plain \TeX\ mode it does not support image inclusion. + \item + Text inside |pgfpicture|s is not supported very well. The reason + is that the \textsc{svg} specification currently does not support + text very well and it is also not possible to correctly ``escape + back'' to \textsc{html}. All these problems will hopefully + disappear in the future, but currently only two kinds of text work + reasonably well: First, plain text without math mode, special + characters or anything else special. Second, \emph{very} simple + mathematical text that contains subscripts or superscripts. Even + then, variables are not correctly set in italics and, in general, + text simple does not look very nice. + \item + If you use text that contains anything special, even something as + simple as |$\alpha$|, this may corrupt the graphic since |text4ht| + does not always produce valid \textsc{xml} code. So, once more, + \emph{stick to very simple node text inside graphics.} Sorry. + \item + Unlike for other output formats, the bounding box of a picture + ``really crops'' the picture. + \end{enumerate} + + The driver basically works as follows: When a |{pgfpicture}| is + started, appropriate |\special| commands are used to directed the + output of |tex4ht| to a new file called |\jobname-xxx.svg|, where + |xxx| is a number that is increased for each graphic. Then, till the + end of the picture, each (system layer) graphic command creates a + specials that insert appropriate \textsc{svg} literal text into the + output file. The exact details are a bit complicated since the + imaging model and the processing model of PostScript/\pdf\ and + \textsc{svg} are not quite the same; but they are ``close enough'' + for \pgfname's purposes. +\end{filedescription} + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-guidelines.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-guidelines.tex new file mode 100644 index 00000000000..06088165c75 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-guidelines.tex @@ -0,0 +1,771 @@ +% $Header: /cvsroot/pgf/pgf/doc/pgf/text-en/pgfmanual-en-guidelines.tex,v 1.1 2005/09/02 16:05:42 tantau Exp $ + +% Copyright 2005 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the GNU Public License, version 2. + + + +\section{Guidelines on Graphics} + +The present section is not about \pgfname\ or \tikzname, but about +general guidelines and principles concerning the creation of +graphics for scientific presentations, papers, and books. + +The guidelines in this section come from different sources. Many of +them are just what I would like to claim is ``common sense,'' some +reflect my personal experience (though, hopefully, not my personal +preferences), some come from books (the bibliography is still missing, +sorry) on graphic design and typography. +The most influential source are the brilliant books +by Edward Tufte. While I do not agree with everything written in these +books, many of Tufte's arguments are so convincing that I decided to +repeat them in the following guidelines. + + + + +\subsection{Should You Follow Guidelines?} + +The first thing you should ask yourself when someone presents a bunch of +guidelines is: Should I really follow these guidelines? This is an +important questions, because there are good reasons not to follow +general guidelines. +\begin{itemize} +\item + The person who setup the guidelines may have had other + objectives than you do. For example, a guideline might say ``use the + color red for emphasis.'' While this guideline makes perfect sense + for, say, a presentation using a projector, red ``color'' has the + \emph{opposite} effect of ``emphasis'' when printed using a + black-and-white printer. + + Guidelines were almost always setup to address a specific + situation. If you are not in this situation, following a guideline + can do more harm than good. +\item + The basic rule of typography is: ``Every rule can be broken, as long + as you are \emph{aware} that you are breaking a rule.'' This rule + also applies to graphics. Phrased differently, the basic rule + states: ``The only mistakes in typography are things done is + ignorance.'' + + When you are aware of a rule and when you decide that breaking the + rule has a desirable effect, break the rule. +\item + Some guidelines are simply \emph{wrong}, but everyone follows them + out of tradition or is forced to do so. My favorite example is a + guideline a software company I used to work for has set in a big + project: All programmers had to declare the parameters of functions + in \emph{increasing order of size}. So, one-byte + parameters should come first, then two-byte parameters, and so on. + + This guideline is total nonsense. An (arguably) sensible guideline + is ``parameters must be declared alphabetically'' so that parameters + are easier to find. Another (arguably) sensible guideline is + ``parameters must be declared in decreasing order of size'' so that + less byte-alignment cache misses occur when the stack is + accessed. The guideline the company used maximized cache misses and + resulted in a more or less random ordering so that programmers + constantly had to look up the parameter ordering. +\end{itemize} + +So, before you apply a guideline or choose not to apply it, ask +yourself these questions: +\begin{enumerate} +\item + Does this guideline really address my situation? +\item + If you do the opposite a guideline says you should do, will the + advantages outweigh the disadvantages this guideline was supposed to + prevent? +\end{enumerate} + + + +\subsection{Planning the Time Needed for the Creation of Graphics} + +When you create a paper with numerous graphics, the time needed to +create these graphics becomes an important factor. How much time +should you calculate for the creation of graphics? + +As a general rule, assume that a graphic will need as much time to +create as would a text of the same length. For example, when I +write a paper, I need about one hour per page for +the first draft. Later, I need between two and four hours per page +for revisions. Thus, I expect to need about half an hour for the +creation of \emph{a first draft} of a half page graphic. Later on, I +expect another one to two hours before the final graphic is finished. + +In many publications, even in good journals, the authors and editors +have obviously invested a lot of time on the text, but seem to +have spend about five minutes to create all of the +graphics. Graphics often seem to have been added as an +``afterthought'' or look like a screen shot of whatever the authors's +statistical software shows them. As will be argued later on, the +graphics that programs like \textsc{gnuplot} produce by default are of +poor quality. + +Creating informative graphics that help the reader and that fit +together with the main text is a difficult, lengthy process. +\begin{itemize} +\item + Treat graphics as first-class citizens of your papers. They deserve + as much time and energy as the text does. +\item + Arguably, the creation of graphics deserves \emph{even more} time + than the writing of the main text since more attention will be paid + to the graphics and they will be looked at first. +\item + Plan as much time for the creation and revision of a graphic as you + would plan for text of the same size. +\item + Difficult graphics with a high information density may require even + more time. +\item + Very simple graphics will require less time, but most likely you do + not want to have ``very simple graphics'' in your paper, anyway; + just as you would not like to have a ``very simple text'' of the + same size. +\end{itemize} + + + +\subsection{Workflow for Creating a Graphic} + +When you write a (scientific) paper, you will most likely follow the +following pattern: You have some results/ideas that you would +like to report about. The creation of the paper will typically start +with compiling a rough outline. Then, the different sections are +filled with text to create a first draft. This draft is then revised +repeatedly until, often after substantial revision, a final paper +results. In a good journal paper there is typically not be a single +sentence that has survived unmodified from the first draft. + +Creating a graphics follows the same pattern: +\begin{itemize} +\item + Decide on what the graphic should communicate. Make this a conscious + decision, that is, determine ``What is the graphic supposed to tell + the reader?'' +\item + Create an ``outline,'' that is, the rough overall ``shape'' of the + graphic, containing the most crucial elements. Often, it is + useful to do this using pencil and paper. +\item + Fill out the finer details of the graphic to create a first + draft. +\item + Revise the graphic repeatedly along with the rest of the paper. +\end{itemize} + + + + +\subsection{Linking Graphics With the Main Text} + +Graphics can be placed at different places in a text. Either, they can +be inlined, meaning they are somewhere ``in the middle of the text'' +or they can be placed in standalone ``figures.'' Since printers (the +people) like to have their pages ``filled,'' (both for aesthetic and +economic reasons) standalone figures may traditionally be placed on +pages in the document far removed from the main text that refers to +them. \LaTeX\ and \TeX\ tend to encourage this ``drifting away'' of +graphics for technical reasons. + +When a graphic is inlined, it will more or less automatically be +linked with the main text in the sense that the labels of the graphic +will be implicitly explained by the surrounding text. Also, the main +text will typically make it clear what the graphic is about and what +is shown. + +Quite differently, a standalone figure will often be viewed at a time +when the main text that this graphic belongs to either has not yet +been read or has been read some time ago. For this reason, you should +follow the following guidelines when creating standalone figures: +\begin{itemize} +\item + Standalone figures should have a caption than should make them + ``understandable by themselves.'' + + For example, suppose a graphic shows an example of the different + stages of a quicksort algorithm. Then the figure's caption should, + at the very least, inform the reader that ``The figure shows the + different stages of the quicksort algorithm introduced on page + xyz.'' and not just ``Quicksort algorithm.'' +\item + A good caption adds as much context information as possible. For + example, you could say: ``The figure shows the different stages of + the quicksort algorithm introduced on page xyz. In the first line, + the pivot element 5 is chosen. This causes\dots'' While this + information can also be given in the main text, putting it in the + caption will ensure that the context is kept. Do not feel afraid of + a 5-line caption. (Your editor may hate you for this. Consider + hating them back.) +\item + Reference the graphic in your main text as in ``For an example of + quicksort `in action,' see Figure~2.1 on page xyz.'' +\item + Most books on style and typography recommend that you do not use + abbreviations as in ``Fig.~2.1'' but write ``Figure 2.1.'' + + The main argument against abbreviations is that ``a period is too + valuable to waste it on an abbreviation.'' The idea is that a period + will make the reader assume that the sentence ends after ``Fig'' and + it takes a ``conscious backtracking'' to realize that the sentence + did not end after all. + + The argument in favor of abbreviations is that they save space. + + Personally, I am not really convinced by either argument. On the one + hand, I have not yet seen any hard evidence that abbreviations slow + readers down. On the other hand, abbreviating all ``Figure'' by + ``Fig.''\ is most unlikely to save even a single line in most + documents. + + I avoid abbreviations. +\end{itemize} + + + +\subsection{Consistency Between Graphics and Text} + +Perhaps the most common ``mistake'' people do when creating graphics +(remember that a ``mistake'' in design is always just ``ignorance'') +is to have a mismatch between the way their graphics look and the way +their text looks. + +It is quite common that authors use several different programs for +creating the graphics of a paper. An author might produce some plots +using \textsc{gnuplot}, a diagram using \textsc{xfig}, and include an +|.eps| graphic a coauthor contributed using some unknown program. All +these graphics will, most likely, use different line widths, different +fonts, and have different sizes. In addition, authors often use +options like |[height=5cm]| when including graphics to scale them to +some ``nice size.'' + +If the same approach were taken to writing the main text, every +section would be written in a different font at a different size. In +some sections all theorems would be underlined, in another they would +be printed all in uppercase letters, and in another in red. In +addition, the margins would be different on each page. + +Readers and editors would not tolerate a text if it were written in +this fashion, but with graphics they often have to. + +To create consistency between graphics and text, stick to the +following guidelines: +\begin{itemize} +\item + Do not scale graphics. + + This means that when generating graphics using an external program, + create them ``at the right size.'' +\item + Use the same font(s) both in graphics and the body text. +\item + Use the same line width in text and graphics. + + The ``line width'' for normal text is the width of the stem of + letters like T{}. For \TeX, this is usually + $0.4\,\mathrm{pt}$. However, some journals will not accept graphics + with a normal line width below $0.5\,\mathrm{pt}$. +\item + When using colors, use a consistent color coding in the text and in + graphics. For example, if red is supposed to alert the reader to + something in the main text, use red also in graphics for important + parts of the graphic. If blue is used for structural elements like + headlines and section titles, use blue also for structural elements + of your graphic. + + However, graphics may also use a logical intrinsic color + coding. For example, no matter what colors you normally use, readers + will generally assume, say, that the color green as ``positive, go, + ok'' and red as ``alert, warning, action.'' +\end{itemize} + +Creating consistency when using different graphic programs is almost +impossible. For this reason, you should consider sticking to a single +graphic program. + + +\subsection{Labels in Graphics} + +Almost all graphics will contain labels, that is, pieces of text that +explain parts of the graphics. When placing labels, stick to the +following guidelines: + +\begin{itemize} +\item + Follow the rule of consistency when placing labels. You should do + so in two ways: First, be consistent with the main text, that is, + use the same font as the main text also for labels. Second, be + consistent between labels, that is, if you format some labels in + some particular way, format all labels in this way. +\item + In addition to using the same fonts in text and graphics, you should + also use the same notation. For example, if you write $1/2$ in your + main text, also use ``$1/2$'' as labels in graphics, not + ``0.5''. A $\pi$ is a ``$\pi$'' and not ``$3.141$''. Finally, + $\mathrm e^{-\mathrm i \pi}$ is ``$\mathrm e^{-\mathrm i \pi}$'', + not ``$-1$'', let alone ``-1''. +\item + Labels should be legible. They should not only have a reasonably + large size, they also should not be obscured by lines or other + text. This also applies to of lines and text \emph{behind} the + labels. +\item + Labels should be ``in place.'' Whenever there is enough space, + labels should be placed next to the thing they label. Only if + necessary, add a (subdued) line from the label to the labeled + object. Try to avoid labels that only reference explanations in + external legends. Reader have to jump back and forth between the + explanation and the object that is described. +\item + Consider subduing ``unimportant'' labels using, for example, a gray + color. This will keep the focus on the actual graphic. +\end{itemize} + + + +\subsection{Plots and Charts} + +One of the most frequent kind of graphics, especially in scientific +papers, are \emph{plots}. They come in a large variety, including +simple line plots, parametric plots, three dimensional plots, pie +charts, and many more. + +Unfortunately, plots are notoriously hard to get right. Partly, the +default settings of programs like \textsc{gnuplot} or Excel are to +blame for this since these programs make it very convenient to create +bad plots. + +The first question you should ask yourself when creating a plot is the +following: +\begin{itemize} +\item + Are there enough data points to merit a plot? +\end{itemize} + +If the answer is ``not really,'' use a table. + +A typical situation where a plot is unnecessary is when people present +a few numbers in a bar diagram. Here is a real-life example: At the +end of a seminar a lecturer asked the participants for feedback. Of +the 50 participants, 30 returned the feedback form. According to the +feedback, three participants considered the seminar ``very good,'' +nine considered it ``good,'' ten ``ok,'' eight ``bad,'' and no one thought +that the seminar was ``very bad.'' + +A simple way of summing up this information is the following table: + +\medskip +\begin{tabular}{lp{3.75cm}r} + \emph{Rating given} & \raggedright\emph{Participants (out of 50) who gave this rating} & + \emph{Percentage} \\[1.75em] + ``very good'' & \hfil\hphantom{0}3\hfil & \hphantom{0}6\% \\ + ``good'' & \hfil\hphantom{0}9\hfil & 18\% \\ + ``ok'' & \hfil10\hfil & 20\% \\ + ``bad'' & \hfil\hphantom{0}8\hfil & 16\% \\ + ``very bad'' & \hfil\hphantom{0}0\hfil & \hphantom{0}0\% \\[2mm] + none & \hfil20\hfil & 40\% \\ +\end{tabular} + +\bigskip +What the lecturer did was to visualize the data using a 3D bar +diagram. It looked like this: + +\bigskip +\par +\begin{tikzpicture}[y=0.03cm,z=3mm] + \foreach \y in {0,20,40,60,80,100} + \draw[dashed] (0,\y,0) node[left] {\y} -- (0,\y,1) -- (6,\y,1); + + \draw (0,0,0) -- (0,100,0) (0,0,1) -- (0,100,1); + \draw (0,0,0) -- (6,0,0); + + \foreach \x/\xtext/\height in {1/very good/10,2/good/30,3/ok/33,4/bad/27,5/very bad/0} + { + \draw (\x,0) node[rotate=90,anchor=east] {\xtext}; + + \begin{scope}[xshift=\x cm] + + \filldraw[fill=blue!50] (-.3,0,0) rectangle (.3,\height,0); + \filldraw[fill=blue!30] (.3,0,0) -- (.3,0,1) -- (.3,\height,1) -- (.3,\height,0) --cycle; + \filldraw[fill=blue!20] (-.3,\height,0) -- (.3,\height,0) -- + (.3,\height,1) -- (-.3,\height,1) --cycle; + \end{scope} + } +\end{tikzpicture} +\bigskip + +Both the table and the ``plot'' have about the same size. If your first +thought is ``the graphic looks nicer than the table,'' try to answer +the following questions based on the information in the table or in +the graphic: +\begin{enumerate} +\item + How many participants where there? +\item + How many participants returned the feedback form? +\item + What percentage of the participants returned the feedback form? +\item + How many participants checked ``very good''? +\item + What percentage out of all participants checked ``very good''? +\item + Did more than a quarter of the participants check ``bad'' or ``very bad''? +\item + What percentage of the participants that returned the form checked ``very good''? +\end{enumerate} + +Sadly, the graphic does not allow us to answer \emph{a single one of these + questions}. The table answers all of them directly, except for the last +one. In essence, the information density of the graphic is very +nearly zero. The table has a much higher information density; despite +the fact that it uses quite a lot of white space to present a few numbers. + +Here is the list of things that went wrong with the 3D-bar diagram: +\begin{itemize} +\item + The whole graphic is dominated by irritating background lines. +\item + It is not clear what the numbers at the left mean; presumably + percentages, but it might also be the absolute number of + participants. +\item + The labels at the bottom are rotated, making them hard to read. + + (In the real presentation that I saw, the text was rendered at a very + low resolution with about 10 by 6 pixels per letter with wrong + kerning, making the rotated text almost impossible to read.) +\item + The third dimension adds complexity to the graphic without adding + information. +\item + The three dimensional setup makes it much harder to gauge the height + of the bars correctly. Consider the ``bad'' bar. It the number this + bar stands for more than 20 or less? While the front of the bar is + below the 20 line, the back of the bar (which counts) is above. +\item + It is impossible to tell which numbers are represented by the + bars. Thus, the bars needlessly hide the information these bars are + all about. +\item + What do the bar heights add up to? Is it 100\% or 60\%? +\item + Does the bar for ``very bad'' represent 0 or~1? +\item + Why are the bars blue? +\end{itemize} + +You might argue that in the example the exact numbers are not +important for the graphic. The important things is the ``message,'' +which is that there are more ``very good'' and ``good'' ratings than +``bad'' and ``very bad.'' However, to convey this message either use a +sentence that says so or use a graphic that conveys this message more +clearly: + +\medskip +\par +\begin{tikzpicture} + \colorlet{good}{green!75!black} + \colorlet{bad}{red} + \colorlet{neutral}{black!60} + \colorlet{none}{white} + + \node[text centered,text width=3cm]{Ratings given by 50~participants}; + + \begin{scope}[line width=4mm,rotate=270] + \draw[good] (-123:2cm) arc (-123:-101:2cm); + \draw[good!60!white] (-36:2cm) arc (-36:-101:2cm); + \draw[neutral] (-36:2cm) arc (-36:36:2cm); + \draw[bad!60!white] (36:2cm) arc (36:93:2cm); + + \newcount\mycount + \foreach \angle in {0,72,...,3599} + { + \mycount=\angle\relax + \divide\mycount by 10\relax + \draw[black!15,thick] (\the\mycount:18mm) -- (\the\mycount:22mm); + } + + \draw (0:2.2cm) node[below] {``ok'': 10 (20\%)}; + \draw (165:2.2cm) node[above] {none: 20 (40\%)}; + \draw (-111:2.2cm) node[left] {``very good'': 3 (6\%)}; + \draw (-68:2.2cm) node[left] {``good'': 9 (18\%)}; + \draw (65:2.2cm) node[right] {``bad'': 8 (16\%)}; + \draw (93:2.2cm) node[right] {``very bad'': 0 (0\%)}; + \end{scope} + \draw[gray] (0,0) circle (2.2cm) circle (1.8cm); +\end{tikzpicture} + +\bigskip +The above graphic has about the same information density as the table +(about the same size and the same numbers are shown). In addition, one +can directly ``see'' that there are more good or very good ratings +than bad ones. One can also ``see'' that the number of people who gave +no rating at all is not negligible, which is quite common for feedback +forms. + +Charts are not always a good idea. Let us look at an example +that I redrew from a pie chart in \emph{Die Zeit}, June 4th, 2005: + +\bigskip +\par +\begin{tikzpicture} + \begin{scope}[xscale=3.2,yscale=1.2] + + \sffamily + \coordinate (right border) at (2.0cm,-1.7cm); + \coordinate (left border) at (-2.5cm,2.1cm); + + \fill[black!25] ([xshift=-2mm,yshift=1.1cm]left border) rectangle ([xshift=2mm,yshift=-.3cm]right border); + + \node[below right,text width=10cm,inner sep=0pt] at ([yshift=.9cm,xshift=-1mm]left border) + { {\color{black!75} \Large Kohle ist am wichtigsten}\\ + Energiemix bei der deutschen Stromerzeugung 2004}; + + \filldraw[draw=gray,fill=white] ([xshift=-1mm]left border) node[below right,black] + {\footnotesize Gesamte Netto-Stromerzeugung in Prozent, in + Milliarden Kilowattstunden (Mrd.\ kWh)} + rectangle ([xshift=1mm]right border); + + % The 3D stuff + \pgfdeclarehorizontalshading{zeit}{100bp} + {color(0pt)=(black); + color(25bp)=(black); + color(37bp)=(white); + color(50bp)=(black); + color(62bp)=(white); + color(75bp)=(black); + color(100bp)=(black)} + + \shadedraw[very thin,shading=zeit,yshift=-1.5mm] (0,0) circle (1cm); + + \fill[green!20!gray] (0,0) -- (90:1cm) arc (90:-5:1cm); + \fill[white!20!gray] (0,0) -- (-5:1cm) arc (-5:-105:1cm); + \fill[orange!20!gray] (0,0) -- (-105:1cm) arc (-105:-180:1cm); + \fill[orange!60!white] (0,0) -- (180:1cm) arc (180:150:1cm); + \fill[black!75!white] (0,0) -- (150:1cm) arc (150:145:1cm); + \fill[blue!90!white] (0,0) -- (145:1cm) arc (145:135:1cm); + \fill[blue!50!white] (0,0) -- (135:1cm) arc (135:92:1cm); + \fill[yellow!50!black] (0,0) -- (92:1cm) arc (92:90:1cm); + + \begin{scope}[very thin] + \draw (0,0) -- (90:1cm); + \draw (0,0) -- (-5:1cm); + \draw (0,0) -- (-105:1cm); + \draw (0,0) -- (-180:1cm); + \draw (0,0) -- (150:1cm); + \draw (0,0) -- (145:1cm); + \draw (0,0) -- (135:1cm); + \draw (0,0) -- (92:1cm); + + \draw(0,0) circle (1cm); + \end{scope} + + \node (Regenerative) at (115:.75cm) {\bfseries 9,4\%}; + \node (Kernenergie) at (30:.5cm) {\bfseries 27,8\%}; + \node (Braunkohle) at (-45:.6cm) {\bfseries 25,6\%}; + \node (Steinkohle) at (-135:.6cm) {\bfseries 22,3\%}; + \node (Erdgas) at (168:.75cm) {\bfseries 10,4\%}; + \coordinate (Mineral) at (147:.9cm); + \coordinate (Sonstige) at (140:.9cm); + + \small + \draw (Regenerative.north) |- ([yshift=.25cm]Regenerative.north -| right border) coordinate (Regenerative label); + \draw (91:.9cm) |- (Regenerative label); + \node[above left] at (Regenerative label) {Regenerative\ + {\footnotesize (53,7 kWh)/davon} Wind \textbf{4,4\%} \footnotesize (25,0 kWh)}; + + \draw (Kernenergie.base east) -- (Kernenergie.base east -| right border) coordinate (Kernenergie label); + \node[above left] at (Kernenergie label) {Kernenergie}; + \node[below left] at (Kernenergie label) {\footnotesize (158,4 kWh)}; + + \draw (Braunkohle.south) |- ([yshift=-.75cm]Braunkohle.south -| right border) coordinate (Braunkohle label); + \node[above left] at (Braunkohle label) {Braunkohle\ \ \footnotesize (146,0 kWh)}; + + \draw (Steinkohle.south) |- ([yshift=-.75cm]Steinkohle.south -| left border) coordinate (Steinkohle label); + \node[above right] at (Steinkohle label) {Steinkohle\ \ \footnotesize (127,1 kWh)}; + + \draw (Erdgas.base west) -- (Erdgas.base west -| left border) coordinate (Erdgas label); + \node[above right] at (Erdgas label) {Erdgas\ \ \footnotesize (59,2 kWh)}; + + \draw (Mineral) -- (Mineral -| left border) coordinate (Mineral label); + \node[above right] at (Mineral label) {Mineral\"olprodukte\ \ + \footnotesize (9,2 kWh) \ \ \normalsize\textbf{1,6\%}}; + + \draw (Sonstige) |- (Regenerative label -| left border) coordinate (Sonstige label); + \node[above right] at (Sonstige label) {Sonstige\ \ + \footnotesize (16,5 kWh) \hskip1.5cm\ + \normalsize\textbf{2,9\%}}; + \end{scope} +\end{tikzpicture} + +This graphic has been redrawn in \tikzname, but the original looks very +similar. + +At first sight, the graphic looks ``nice and informative,'' but there +are a lot of things that went wrong: + +\begin{itemize} +\item + The chart is three dimensional. However, the shadings add + nothing ``information-wise,'' at best, they distract. +\item + In a 3D-pie-chart the relative sizes are very strongly + distorted. For example, the area taken up by the gray color of ``Braunkohle'' + is larger than the area taken up by the green color of + ``Kernenergie'' \emph{despite the fact that the percentage of + Braunkohle is less than the percentage of Kernenergie}. +\item + The 3D-distortion gets worse for small areas. The area of + ``Regenerative'' somewhat larger than the area of ``Erdgas.'' + The area of ``Wind'' is slightly smaller than the area of + ``Mineral\"olprodukte'' \emph{although the percentage of Wind is + nearly three times larger than the percentage of + Mineral\"olprodukte.} + + In the last case, the different sizes are only partly due to + distortion. The designer(s) of the original graphic have also made + the ``Wind'' slice too small, even taking distortion into + account. (Just compare the size of ``Wind'' to ``Regenerative'' in + general.) +\item + According to its caption, this chart is supposed to inform us that + coal was the most important energy source in Germany in + 2004. Ignoring the strong distortions caused by the superfluous and + misleading 3D-setup, it takes quite a while for this message to get + across. + + Coal as an energy source is split up into two slices: one for + ``Steinkohle'' and one for ``Braunkohle'' (two different kinds of + coal). When you add them up, you see that the whole lower half of + the pie chart is taken up by coal. + + The two areas for the different kinds of coal are not visually + linked at all. Rather, two different colors are used, the labels are + on different sides of the graphic. By comparison, ``Regenerative'' + and ``Wind'' are very closely linked. +\item + The color coding of the graphic follows no logical pattern at + all. Why is nuclear energy green? Regenerative energy is light blue, + ``other sources'' are blue. It seems more like a joke that the area + for ``Braunkohle'' (which literally translates to ``brown coal'') is + stone gray, while the area for ``Steinkohle'' (which literally + translates to ``stone coal'') is brown. +\item + The area with the lightest color is used for ``Erdgas.'' This area + stands out most because of the brighter color. However, for this + chart ``Erdgas'' is not really important at all. +\end{itemize} +Edward Tufte calls graphics like the above ``chart junk.'' + +Here are a few recommendations that may help you avoid producing chart junk: +\begin{itemize} +\item + Do not use 3D pie charts. They are \emph{evil}. +\item + Consider using a table instead of a pie chart. +\item + Due not apply colors randomly; use them to direct the readers's + focus and to group things. +\item + Do not use background patterns, like a crosshatch or diagonal + lines, instead of colors. They distract. Background patterns in + information graphics are \emph{evil}. +\end{itemize} + + + +\subsection{Attention and Distraction} + +Pick up your favorite fiction novel and have a look at a typical +page. You will notice that the page is very uniform. Nothing is there +to distract the reader while reading; no large headlines, no bold +text, no large white areas. Indeed, even when the author does wish to +emphasize something, this is done using italic letters. Such letters +blend nicely with the main text---at a distance you will not be able to +tell whether a page contains italic letters, but you would notice a +single bold word immediately. The reason novels are typeset this way +is the following paradigm: Avoid distractions. + +Good typography (like good organization) is something you do +\emph{not} notice. The job of typography is to make reading the text, +that is, ``absorbing'' its information content, as effortless as +possible. For a novel, readers absorb the content by reading the text +line-by-line, as if they were listening to someone telling the +story. In this situation anything on the page that distracts the eye +from going quickly and evenly from line to line will make the text +harder to read. + +Now, pick up your favorite weekly magazine or newspaper and have a +look at a typical +page. You will notice that there is quite a lot ``going on'' on the +page. Fonts are used at different sizes and in different arrangements, +the text is organized in narrow columns, typically interleaved with +pictures. The reason magazines are typeset in this way is another +paradigm: Steer attention. + +Readers will not read a magazine like a novel. Instead of reading a +magazine line-by-line, we use headlines and short abstracts to check +whether we want to read a certain article or not. The job of +typography is to steer our attention to these abstracts and headlines, +first. Once we have decided that we want to read an article, however, +we no longer tolerate distractions, which is why the main text of +articles is typeset exactly the same way as a novel. + +The two principles ``avoid distractions'' and ``steer attention'' also +apply to graphics. When you design a graphic, you should eliminate +everything that will ``distract the eye.'' At the same time, you +should try to actively help the reader ``through the graphic'' by +using fonts/colors/line widths to highlight different parts. + +Here is a non-exhaustive list of things that can distract readers: +\begin{itemize} +\item + Strong contrasts will always be registered first by the eye. For + example, consider the following two grids: + + \medskip\par + \begin{tikzpicture}[x=40pt,y=40pt] + \draw[step=10pt,gray] (0,0) grid +(1,1); + \draw[step=2pt] (2,0) grid +(1,1); + \end{tikzpicture} + + \medskip + Even though the left grid comes first in our normal reading order, + the right one is much more likely to be seen first: The + white-to-black contrast is higher than the gray-to-white + contrast. In addition, there are more ``places'' adding to the + overall contrast in the right grid. + + Things like grids and, more generally, help lines usually should not + grab the attention of the readers and, hence, should be typeset with + a low contrast to the background. Also, a loosely-spaced grid is + less distracting than a very closely-spaced grid. +\item + Dashed lines create many points at which there is black-to-white + contrast. Dashed or dotted lines can be very distracting and, hence, + should be avoided in general. + + Do not use different dashing patterns to differentiate curves in + plots. You loose data points this way and the eye is not + particularly good at ``grouping things according to a dashing + pattern.'' The eye is \emph{much} better at grouping things + according to colors. +\item + Background patterns filling an area using diagonal lines or + horizontal and vertical lines or just dots are almost always + distracting and, usually, serve no real purpose. +\item + Background images and shadings distract and only seldom add + anything of importance to a graphic. +\item + Cute little cliparts can easily draw attention away from the + data. +\end{itemize} + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-installation.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-installation.tex new file mode 100644 index 00000000000..e925f6a599f --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-installation.tex @@ -0,0 +1,182 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Installation} + +There are different ways of installing \pgfname, depending +on your system and needs, and you may need to install other +packages as well as, see below. Before installing, you may wish to +review the \textsc{gpl} license under which the package is +distributed, see Section~\ref{section-license}. + +Typically, the package will already be installed on your +system. Naturally, in this case you do not need to worry about the +installation process at all and you can skip the rest of this +section. + + +\subsection{Package and Driver Versions} + +This documentation is part of version \pgfversion\ of the \pgfname\ +package. In order to run \pgfname, you need a reasonably recent +\TeX\ installation. When using \LaTeX, you need the following packages +installed (newer versions should also work): +\begin{itemize} +\item + |xcolor| version \xcolorversion. +\item + |xkeyval| version \xkeyvalversion, if you wish to use \tikzname. +\end{itemize} +With plain \TeX, |xcolor| is not needed, but you obviously do not +get its (full) functionality. + +Currently, \pgfname\ supports the following backend drivers: +\begin{itemize} +\item + |pdftex| version 0.14 or higher. Earlier versions do not work. +\item + |dvips| version 5.94a or higher. Earlier versions may also work. +\item + |dvipdfm| version 0.13.2c or higher. Earlier versions may also work. +\item + |tex4ht| version 2003-05-05 or higher. Earlier versions may also work. +\item + |vtex| version 8.46a or higher. Earlier versions may also work. +\end{itemize} + +Currently, \pgfname\ supports the following formats: +\begin{itemize} +\item + |latex| with complete functionality. +\item + |plain| with complete functionality, except for graphics inclusion, + which works only for pdf\TeX. +\item + |context| should work as |plain|, but I have not tried it. +\end{itemize} + +For more details, see Section~\ref{section-formats}. + + + +\subsection{Installing Prebundled Packages} + +I do not create or manage prebundled packages of \pgfname, but, +fortunately, nice other people do. I cannot give detailed instructions +on how to install these packages, since I do not manage them, but I +\emph{can} tell you were to find them. If you have a problem with +installing, you might wish to have a look at the Debian page or the +Mik\TeX\ page first. + + +\subsubsection{Debian} + +The command ``|aptitude install pgf|'' should do the trick. Sit back +and relax. In detail, the following packages are installed: +\begin{verbatim} +http://packages.debian.org/pgf +http://packages.debian.org/latex-xcolor +\end{verbatim} + + +\subsubsection{MiKTeX} + +For MiK\TeX, use the update wizard to install the (latest versions of +the) packages called |pgf|, |xcolor|, and |xkeyval|. + + + + +\subsection{Installation in a texmf Tree} + +For a permanent installation, you place the files of the +the \textsc{pgf} package in an appropriate |texmf| tree. + +When you ask \TeX\ to use a certain class or package, it usually looks +for the necessary files in so-called |texmf| trees. These trees +are simply huge directories that contain these files. By default, +\TeX\ looks for files in three different |texmf| trees: +\begin{itemize} +\item + The root |texmf| tree, which is usually located at + |/usr/share/texmf/| or |c:\texmf\| or somewhere similar. +\item + The local |texmf| tree, which is usually located at + |/usr/local/share/texmf/| or |c:\localtexmf\| or somewhere similar. +\item + Your personal |texmf| tree, which is usually located in your home + directory at |~/texmf/| or |~/Library/texmf/|. +\end{itemize} + +You should install the packages either in the local tree or in +your personal tree, depending on whether you have write access to the +local tree. Installation in the root tree can cause problems, since an +update of the whole \TeX\ installation will replace this whole tree. + + +\subsubsection{Installation that Keeps Everything Together} + +Once you have located the right texmf tree, you must decide whether +you want to install \pgfname\ in such a way that ``all its files are +kept in one place'' or whether you want to be +``\textsc{tds}-compliant,'' where \textsc{tds} means ``\TeX\ directory +structure.'' + +If you want to keep ``everything in one place,'' inside the |texmf| +tree that you have chosen create a sub-sub-directory called +|texmf/tex/generic/pgf| or +|texmf/tex/generic/pgf-|\texttt{\pgfversion}, if you prefer. Then +place all files of the |pgf| package in this directory. Finally, +rebuild \TeX's filename database. This is done by running the command +|texhash| or |mktexlsr| (they are the same). In Mik\TeX, there is a +menu option to do this. + + +\subsubsection{Installation that is TDS-Compliant} + +While the above installation process is the most ``natural'' one and +although I would like to recommend it since it makes updating and +managing the \pgfname\ package easy, it is not +\textsc{tds}-compliant. If you want to be \textsc{tds}-compliant, +proceed as follows: (If you do not know what \textsc{tds}-compliant +means, you probably do not want to be \textsc{tds}-compliant.) + +The |.tar| file of the |pgf| package contains the following files and +directories at its root: |README|, |doc|, |generic|, |plain|, and +|latex|. You should ``merge'' each of the four directories with the +following directories |texmf/doc|, |texmf/tex/generic|, +|texmf/tex/plain|, and |texmf/tex/latex|. For example, in the |.tar| +file the |doc| directory contains just the directory |pgf|, and this +directory has to be moved to |texmf/doc/pgf|. The root |README| file +can be ignored since it is reproduced in |doc/pgf/README|. + +You may also consider keeping everything in one place and using +symbolic links to point from the \textsc{tds}-compliant directories to +the central installation. + +\vskip1em +For a more detailed explanation of the standard installation process +of packages, you might wish to consult +\href{http://www.ctan.org/installationadvice/}{|http://www.ctan.org/installationadvice/|}. +However, note that the \pgfname\ package does not come with a +|.ins| file (simply skip that part). + + +\subsection{Updating the Installation} + +To update your installation from a previous version, all you need to +do is to replace everything in the directory |texmf/tex/generic/pgf| +with the files of the new version (or in all the directories where +|pgf| was installed, if you chose a \textsc{tds}-compliant +installation). The easiest way to do this is to first delete the old +version and then proceed as described above. Sometimes, there are +changes in the syntax of certain command from version to version. If +things no longer work that used to work, you may wish to have a look +at the release notes and at the change log. + + +\input{pgfmanual-en-license} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex new file mode 100644 index 00000000000..fd67dafc38c --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex @@ -0,0 +1,236 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + + +\section{Introduction} + +The \pgfname\ package, where ``\pgfname'' is supposed to mean ``portable +graphics format'' (or ``pretty, good, functional'' if you +prefer\dots), is a package for creating graphics in an ``inline'' +manner. The package defines a number of \TeX\ commands that draw +graphics. For example, the code |\tikz \draw (0pt,0pt) -- (20pt,6pt);| +yields the line \tikz \draw (0pt,0pt) -- (20pt,6pt); and the code +|\tikz \fill[orange] (1ex,1ex) circle (1ex);| yields \tikz +\fill[orange] (1ex,1ex) circle (1ex);. + +In a sense, when using \pgfname\ you ``program'' your graphics, just as you +``program'' your document when using \TeX. This means that you get +the advantages of the ``\TeX-approach to typesetting'' also for your +graphics: quick creation of simple graphics, precise positioning, the +use of macros, often superior typography. You also inherit all the +disadvantages: steep learning curve, no \textsc{wysiwyg}, small +changes require a long recompilation time, and the code does not +really ``show'' how things will look like. + + + +\subsection{Structure of the System} + +The \pgfname\ system consists of different layers: + +\begin{description} +\item[System layer:] This layer provides a complete abstraction of what is + going on ``in the driver.'' The driver is a program like |dvips| or + |dvipdfm| that takes a |.dvi| file as input and generates a |.ps| or + a |.pdf| file. (The |pdftex| program also counts as a driver, even + though it does not take a |.dvi| file as input. Never mind.) Each + driver has its own syntax for the generation of graphics, causing + headaches to everyone who wants to create graphics in a portable + way. \pgfname's system layer ``abstracts away'' these + differences. For example, the system command + |\pgfsys@lineto{10pt}{10pt}| extends the current path to the coordinate + $(10\mathrm{pt},10\mathrm{pt})$ of the current + |{pgfpicture}|. Depending on whether |dvips|, + |dvipdfm|, or |pdftex| is used to process the document, the system + command will be converted to different |\special| commands. + + The system layer is as ``minimalistic'' as possible since each + additional command makes it more work to port \pgfname\ to a new + driver. Currently, only drivers that produce PostScript or + \textsc{pdf} output are supported and only few of these (hence the + name \emph{portable} graphics format is currently a bit + boastful). However, in principle, the system layer could be ported + to many different drivers quite easily. It should even be possible + to produce, say, \textsc{svg} output in conjunction with + \textsc{tex4ht}. + + As a user, you will not use the system layer directly. +\item[Basic layer:] + The basic layer provides a set of basic commands that allow + you to produce complex graphics in a much easier way than by using + the system layer directly. For example, the system layer provides + no commands for creating circles since circles can be composed from + the more basic Bézier curves (well, almost). However, as a user you + will want to have a simple command to create circles + (at least I do) instead of having to write down half a page of + Bézier curve support coordinates. Thus, the basic layer provides a + command |\pgfpathcircle| that generates the necessary curve + coordinates for you. + + The basic layer is consists of a \emph{core}, which consists of + several interdependent packages that can only be loaded \emph{en + bloc,} and additional packages that extend the core by more + special-purpose commands like node management or a plotting + interface. For instance, the \textsc{beamer} package uses the core, + but not all of the additional packages of the basic layer. +\item[Frontend layer:] + A frontend (of which there can be several) is a set of commands + or a special syntax that makes using the basic layer easier. A + problem with directly using the basic layer is that code written for + this layer is often too ``verbose.'' For example, to draw a simple + triangle, you may need as many as five commands when using the basic + layer: One for beginning a path at the first corner of the triangle, + one for extending the path to the second corner, one for going to + the third, one for closing the path, and one for actually painting + the triangle (as opposed to filling it). With the |tikz| frontend + all this boils down to a single simple \textsc{metafont}-like + command: +\begin{verbatim} +\draw (0,0) -- (1,0) -- (1,1) -- cycle; +\end{verbatim} + + There are different frontends: + \begin{itemize} + \item + The \tikzname\ frontend is the ``natural'' frontend for \pgfname. It gives + you access to all features of \pgfname, but it is intended to be + easy to use. The syntax is a mixture of \textsc{metafont} and + \textsc{pstricks} and some ideas of myself. This frontend is + \emph{neither} a complete \textsc{metafont} compatibility layer nor + a \textsc{pstricks} compatibility layer and it is not intended to + become either. + \item + The |pgfpict2e| frontend reimplements the standard \LaTeX\ + |{picture}| environment and commands like |\line| or |\vector| + using the \pgfname\ basic layer. This layer is not really ``necessary'' + since the |pict2e.sty| package does at least as good a job at + reimplementing the |{picture}| environment. Rather, the idea + behind this package is to have a simple demonstration of how a + frontend can be implemented. + \end{itemize} + + It would be possible to implement a |pgftricks| frontend that maps + \textsc{pstricks} commands to \pgfname\ commands. However, I have not + done this and even if fully implemented, many things that work in + \pstricks\ will not work, namely whenever some \pstricks\ command + relies too heavily on PostScript trickery. Nevertheless, such a + package might be useful in some situations. +\end{description} + +As a user of \pgfname\ you will use the commands of a +frontend plus perhaps some commands of the basic layer. For this +reason, this manual explains the frontends first, then the basic +layer, and finally the system layer. + + + +\subsection{Comparison with Other Graphics Packages} + +There were two main motivations for creating \pgfname: +\begin{enumerate} +\item + The standard \LaTeX\ |{picture}| environment is not powerful enough to + create anything but really simple graphics. This is certainly not + due to a lack of knowledge or imagination on the part of + \LaTeX's designer(s). Rather, this is the price paid for the + |{picture}| environment's portability: It works together with all + backend drivers. +\item + The |{pstricks}| package is certainly powerful enough to create + any conceivable kind of graphic, but it is not portable at all. Most + importantly, it does not work with |pdftex| nor with any other + driver that produces anything but PostScript code. +\end{enumerate} + +The \pgfname\ package is a trade-off between portability and expressive +power. It is not as portable as |{picture}| and perhaps not quite as +powerful as |{pspicture}|. However, it is more powerful than +|{picture}| and more portable than |{pspicture}|. + +\subsection{Utilities: Page Management} + +The \pgfname\ package include a special subpackage called |pgfpages|, +which is used to assemble several pages into a single page. This +package is not really about creating graphics, but it is part of \pgfname\ +nevertheless, mostly because its implementation uses \pgfname\ heavily. + +The subpackage |pgfpages| provides commands for assembling several +``virtual pages'' into a single ``physical page.'' The idea is that +whenever \TeX\ has a page ready for ``shipout,'' |pgfpages| interrupts +this shipout and instead stores the page to be shipped out in a +special box. When enough ``virtual pages'' have been accumulated in +this way, they are scaled down and arranged on a ``physical page,'' +which then \emph{really} shipped out. This mechanism allows you to +create ``two page on one page'' versions of a document directly inside +\LaTeX\ without the use of any external programs. + +However, |pgfpages| can do quite a lot more than that. You can use it +to put logos and watermark on pages, print up to 16 pages on one page, +add borders to pages, and more. + + + + +\subsection{How to Read This Manual} + +This manual describes both the design of the \pgfname\ system and +its usage. The organization is very roughly according to +``user-friendliness.'' The commands and subpackages that are easiest +and most frequently used are described first, more low-level and +esoteric features are discussed later. + +If you have not yet installed \pgfname, please read the installation +first. Second, it might be a good idea to read the tutorial. Finally, +you might wish to skim through the description of \tikzname. Typically, +you will not need to read the sections on the basic layer. You will +only need to read the part on the system layer if you intend to write +your own frontend or if you wish to port \pgfname\ to a new driver. + +The ``public'' commands and environments provided by the |pgf| package +are described throughout the text. In each such description, the +described command, environment or option is printed in red. Text shown +in green is optional and can be left out. + + + +\subsection{Getting Help} + +When you need help with \pgfname\ and \tikzname, please do the +following: + +\begin{enumerate} +\item + Read the manual, at least the part that has to do with your problem. +\item + If that does not solve the problem, try having a look at the + sourceforge development page for \pgfname\ and \tikzname\ (see the + title of this document). Perhaps someone has already reported a + similar problem and someone has found a solution. +\item + On the website you will find numerous forums for getting + help. There, you can write to help forums, file bug reports, join + mailing lists, and so on. +\item + Before you file a bug report, especially a bug report concerning the + installation, make sure that this is really a bug. In particular, + have a look at the |.log| file that results when you \TeX\ your + files. This |.log| file should show that all the right files are + loaded from the right directories. Nearly all installation problems + can be resolved by looking at the |.log| file. +\item + \emph{As a last resort} you can try to email me (the author). I do + not mind getting emails, I simply get way too many of them. Because + of this, I cannot guarantee that your emails will be answered timely + or even at all. Your chances that your problem will be fixed are + somewhat higher if you mail to the \pgfname\ mailing list + (naturally, I read this list and answer questions when I have the + time). +\item + Please, do not phone me in my office. If you need a hotline, buy a + commercial product. +\end{enumerate} + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-libraries.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-libraries.tex new file mode 100644 index 00000000000..3d9b4564c5d --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-libraries.tex @@ -0,0 +1,1094 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Libraries} + +\subsection{Arrow Tip Library} +\label{section-library-arrows} + +\begin{package}{pgflibraryarrows} + The package defines additional arrow tips, which are described + below. See page~\pageref{standard-arrows} for the arrows tips that + are defined by default. Note that neither the standard packages nor + this package defines an arrow name containing |>| or |<|. These are + left for the user to defined as he or she sees fit. +\end{package} + +\subsubsection{Triangular Arrow Tips} + +\begin{tabular}{ll} + \symarrow{latex'} \\ + \symarrow{latex' reversed} \\ + \symarrow{stealth'} \\ + \symarrow{stealth' reversed}\\ + \symarrow{triangle 90} \\ + \symarrow{triangle 90 reversed} \\ + \symarrow{triangle 60} \\ + \symarrow{triangle 60 reversed} \\ + \symarrow{triangle 45} \\ + \symarrow{triangle 45 reversed} \\ + \symarrow{open triangle 90} \\ + \symarrow{open triangle 90 reversed} \\ + \symarrow{open triangle 60} \\ + \symarrow{open triangle 60 reversed} \\ + \symarrow{open triangle 45} \\ + \symarrow{open triangle 45 reversed} \\ +\end{tabular} + +\subsubsection{Barbed Arrow Tips} + +\begin{tabular}{ll} + \symarrow{angle 90} \\ + \symarrow{angle 90 reversed} \\ + \symarrow{angle 60} \\ + \symarrow{angle 60 reversed} \\ + \symarrow{angle 45} \\ + \symarrow{angle 45 reversed} \\ + \symarrow{hooks} \\ + \symarrow{hooks reversed} \\ +\end{tabular} + + +\subsubsection{Bracket-Like Arrow Tips} + +\begin{tabular}{ll} + \sarrow{[}{]} \\ + \sarrow{]}{[} \\ + \sarrow{(}{)} \\ + \sarrow{)}{(} +\end{tabular} + +\subsubsection{Circle and Diamond Arrow Tips} + + +\begin{tabular}{ll} + \symarrow{o} \\ + \symarrow{*} \\ + \symarrow{diamond} \\ + \symarrow{open diamond} \\ +\end{tabular} + + +\subsubsection{Partial Arrow Tips} + +\begin{tabular}{ll} + \symarrow{left to} \\ + \symarrow{left to reversed} \\ + \symarrow{right to} \\ + \symarrow{right to reversed} \\ + \symarrow{left hook} \\ + \symarrow{left hook reversed} \\ + \symarrow{right hook} \\ + \symarrow{right hook reversed} +\end{tabular} + + +\subsubsection{Line Caps} + +\begin{tabular}{ll} + \carrow{round cap} \\ + \carrow{butt cap} \\ + \carrow{triangle 90 cap} \\ + \carrow{triangle 90 cap reversed} \\ + \carrow{fast cap} \\ + \carrow{fast cap reversed} \\ +\end{tabular} + + +\subsection{Snake Library} + +\label{section-library-snakes} + +\begin{package}{pgflibrarysnakes} + This library package defines basic + snakes. Section~\ref{section-tikz-snakes} explains how snakes are + used in \tikzname, Section~\ref{section-base-snakes} explains how + new snakes can be defined. + + The snakes are influenced by the current values of parameters like + |\pgfsnakesegmentamplitude|. Only this parameter and + |\pgfsnakesegmentlength| are proper \TeX\ dimensions, all other + parameters are \TeX\ macros. + + In \tikzname, each parameter can be set using an option having the + parameters name minus the |\pgfsnake| part. +\end{package} + + +\begin{snake}{border} + This snake adds straight lines the path that are at a specific angle + to the line toward the target. The idea is to add these little lines + to indicate the ``border'' or an area. The following parameters + influence the snake: + \begin{itemize} + \item |\pgfsnakesegmentlength| + determines the distance between consecutive ticks. + \item |\pgfsnakesegmentamplitude| + determines the length of the ticks. + \item |\pgfsnakesegmentangle| + determines the angle between the ticks and the line toward the + target. + \end{itemize} +\begin{codeexample}[] +\tikz{\draw (0,0) rectangle (3,1) + [snake=border,segment angle=-45] (0,0) rectangle (3,1);} +\end{codeexample} +\end{snake} + + +\begin{snake}{brace} + This snake adds a long brace to the path. The left and right end of + the brace will be exactly on the start and endpoint of the + snake. The following parameters influence the snake: + \begin{itemize} + \item |\pgfsnakesegmentamplitude| + determines how much the brace rises above the path. + \item |\pgfsnakesegmentaspect| + determines the fraction of the total length where the ``middle + part'' of the brace will be. + \end{itemize} +\begin{codeexample}[] +\tikz{\draw[snake=brace,segment aspect=0.25] (0,0) -- (3,0);} +\end{codeexample} +\end{snake} + +\begin{snake}{bumps} + This snake consists of little half ellipses. The following parameters + influence the snake: + \begin{itemize} + \item |\pgfsnakesegmentamplitude| + determines the height of the half ellipse. + \item |\pgfsnakesegmentlength| + determines the width of the half ellipse. + \end{itemize} +\begin{codeexample}[] +\tikz{\draw[snake=bumps] (0,0) -- (3,0);} +\end{codeexample} +\end{snake} + + +\begin{snake}{coil} + This snake adds a coil to the path. To understand how this works, + imagine a three-dimensional spring. The spring's axis points along + the line toward the target. Then, we ``view'' the spring from a + certain angle. If we look ``straight from the side'' we will see a + perfect sine curve, if we look ``more from the front'' we will see a + coil. The following parameters influence the snake: + \begin{itemize} + \item |\pgfsnakesegmentamplitude| + determines how much the coil rises above the path and falls below + it. Thus, this is the radius of the coil. + \item |\pgfsnakesegmentlength| + determines the distance between two consecutive ``curls.'' Thus, + when the spring is see ``from the side'' this will be the wave + length of the sine curve. + \item |\pgfsnakesegmentaspect| + determines the ``viewing direction.'' A value of |0| means + ``looking from the side'' and a value of |0.5|, which is the + default, means ``look more from the front.'' + \end{itemize} +\begin{codeexample}[] +\begin{tikzpicture}[segment amplitude=10pt] + \draw[snake=coil] (0,1) -- (3,1); + \draw[snake=coil,segment aspect=0] (0,0) -- (3,0); +\end{tikzpicture} +\end{codeexample} +\end{snake} + + +\begin{snake}{expanding waves} + This snake adds arcs to the path that get bigger along the line + towards the target. The following parameters influence the snake: + \begin{itemize} + \item |\pgfsnakesegmentlength| + determines the distance between consecutive arcs. + \item |\pgfsnakesegmentangle| + determines the opening angle below and above the path. Thus, the + total opening angle is twice this angle. + \end{itemize} +\begin{codeexample}[] +\tikz{\draw[snake=expanding waves] (0,0) -- (3,0);} +\end{codeexample} +\end{snake} + + +\begin{snake}{saw} + This snake looks like the blade of a saw. The following parameters + influence the snake: + \begin{itemize} + \item |\pgfsnakesegmentamplitude| + determines how much each spike raises above the straight line. + \item |\pgfsnakesegmentlength| + determines the length each spike. + \end{itemize} +\begin{codeexample}[] +\tikz{\draw[snake=saw] (0,0) -- (3,0);} +\end{codeexample} +\end{snake} + + +\begin{snake}{snake} + This snake is the ``architypical'' snake: It looks like a snake seen + from above. More precisely, the snake is a sine wave with a + ``softened'' start and ending. The following parameters influence + the snake: + \begin{itemize} + \item |\pgfsnakesegmentamplitude| + determines the sine wave's amplitude. + \item |\pgfsnakesegmentlength| + determines the sine wave's wave length. + \end{itemize} +\begin{codeexample}[] +\tikz{\draw[snake=snake] (0,0) -- (3,0);} +\end{codeexample} +\end{snake} + + +\begin{snake}{ticks} + This snake adds straight lines the path that are orthogonal to the + line toward the target. The following parameters influence the snake: + \begin{itemize} + \item |\pgfsnakesegmentlength| + determines the distance between consecutive ticks. + \item |\pgfsnakesegmentamplitude| + determines half the length of the ticks. + \end{itemize} +\begin{codeexample}[] +\tikz{\draw[snake=ticks] (0,0) -- (3,0);} +\end{codeexample} +\end{snake} +\begin{snake}{triangles} + This snake adds triangles to the path that point toward the + target. The following parameters influence the snake: + \begin{itemize} + \item |\pgfsnakesegmentlength| + determines the distance between consecutive triangles. + \item |\pgfsnakesegmentamplitude| + determines half the length of the triangle side that is orthogonal + to the path. + \item |\pgfsnakesegmentobjectlength| + determines the height of the triangle. + \end{itemize} +\begin{codeexample}[] +\tikz{\draw[snake=triangles] (0,0) -- (3,0);} +\end{codeexample} +\end{snake} + + +\begin{snake}{waves} + This snake adds arcs to the path that have a constant size. The + following parameters influence the snake: + \begin{itemize} + \item |\pgfsnakesegmentlength| + determines the distance between consecutive arcs. + \item |\pgfsnakesegmentangle| + determines the opening angle below and above the path. Thus, the + total opening angle is twice this angle. + \item |\pgfsnakesegmentamplitude| + determines the radius of each arc. + \end{itemize} +\begin{codeexample}[] +\tikz{\draw[snake=waves] (0,0) -- (3,0);} +\end{codeexample} +\end{snake} + + +\begin{snake}{zigzag} + This snake looks like a zig-zag line. The following parameters + influence the snake: + \begin{itemize} + \item |\pgfsnakesegmentamplitude| + determines how much the zig-zag lines raises above and falls below + a straight line to the target point. + \item |\pgfsnakesegmentlength| + determines the length of a complete ``up-down'' cycle. + \end{itemize} +\begin{codeexample}[] +\tikz{\draw[snake=zigzag] (0,0) -- (3,0);} +\end{codeexample} +\end{snake} + + + +\subsection{Plot Handler Library} +\label{section-library-plothandlers} + +\begin{package}{pgflibraryplothandlers} + This library packages defines additional plot handlers, see + Section~\ref{section-plot-handlers} for an introduction to plot + handlers. The additional handlers are described in the following. +\end{package} + + +\subsubsection{Curve Plot Handlers} + +\begin{command}{\pgfplothandlercurveto} + This handler will issue a |\pgfpathcurveto| command for each point of + the plot, \emph{except} possibly for the first. As for the line-to + handler, what happens with the first point can be specified using + |\pgfsetmovetofirstplotpoint| or |\pgfsetlinetofirstplotpoint|. + + Obviously, the |\pgfpathcurveto| command needs, in addition to the + points on the path, some control points. These are generated + automatically using a somewhat ``dumb'' algorithm: Suppose you have + three points $x$, $y$, and $z$ on the curve such that $y$ is between + $x$ and $z$: +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlercurveto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + + In order to determine the control points of the curve at the point + $y$, the handler computes the vector $z-x$ and scales it by the + tension factor (see below). Let us call the resulting vector + $s$. Then $y+s$ and $y-s$ will be the control points around $y$. The + first control point at the beginning of the curve will be the + beginning itself, once more; likewise the last control point is the + end itself. +\end{command} + +\begin{command}{\pgfsetplottension\marg{value}} + Sets the factor used by the curve plot handlers to determine the + distance of the control points from the points they control. The + higher the curvature of the curve points, the higher this value + should be. A value of $1$ will cause four points at quarter + positions of a circle to be connected using a circle. The default is + $0.5$. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfsetplottension{0.75} + \pgfplothandlercurveto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfplothandlerclosedcurve} + This handler works like the curve-to plot handler, only it will + add a new part to the current path that is a closed curve through + the plot points. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerclosedcurve + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\subsubsection{Comb Plot Handlers} + +There are three ``comb'' plot handlers. There name stems from the fact +that the plots they produce look like ``combs'' (more or less). + +\begin{command}{\pgfplothandlerxcomb} + This handler converts each point in the plot stream into a line from + the $y$-axis to the point's coordinate, resulting in a ``horizontal + comb.'' + + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerxcomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfplothandlerycomb} + This handler converts each point in the plot stream into a line from + the $x$-axis to the point's coordinate, resulting in a ``vertical + comb.'' + + This handler is useful for creating ``bar diagrams.'' +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerycomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfplothandlerpolarcomb} + This handler converts each point in the plot stream into a line from + the origin to the point's coordinate. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerpolarcomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\subsubsection{Mark Plot Handler} + +\label{section-plot-marks} + +\begin{command}{\pgfplothandlermark\marg{mark code}} + This command will execute the \meta{mark code} for each point of the + plot, but each time the coordinate transformation matrix will be + setup such that the origin is at the position of the point to be + plotted. This way, if the \meta{mark code} draws a little circle + around the origin, little circles will be drawn at each point of the + plot. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + + Typically, the \meta{code} will be |\pgfuseplotmark{|\meta{plot mark + name}|}|, where \meta{plot mark name} is the name of a + predefined plot mark. +\end{command} + +\begin{command}{\pgfuseplotmark\marg{plot mark name}} + Draws the given \meta{plot mark name} at the origin. The \meta{plot + mark name} must previously have been declared using + |\pgfdeclareplotmark|. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfuseplotmark{pentagon}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfdeclareplotmark\marg{plot mark name}\marg{code}} + Declares a plot mark for later used with the |\pgfuseplotmark| + command. + +\begin{codeexample}[] +\pgfdeclareplotmark{my plot mark} + {\pgfpathcircle{\pgfpoint{0cm}{1ex}}{1ex}\pgfusepathqstroke} +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfuseplotmark{my plot mark}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfsetplotmarksize\marg{dimension}} + This command sets the \TeX\ dimension |\pgfplotmarksize| to + \meta{dimension}. This dimension is a ``recommendation'' for plot + mark code at which size the plot mark should be drawn; plot mark + code may choose to ignore this \meta{dimension} altogether. For + circles, \meta{dimension} should be the radius, for other shapes it + should be about half the width/height. + + The predefined plot marks all take this dimension into account. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfsetplotmarksize{1ex} + \pgfplothandlermark{\pgfuseplotmark{*}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{textoken}{\pgfplotmarksize} + A \TeX\ dimension that is a ``recommendation'' for the size of plot + marks. +\end{textoken} + +The following plot marks are predefined (the filling color has been +set to yellow): + +\medskip +\begin{tabular}{lc} + \plotmarkentry{*} + \plotmarkentry{x} + \plotmarkentry{+} +\end{tabular} + + +\subsection{Plot Mark Library} + +\begin{package}{pgflibraryplotmarks} + When this package is loaded, the following plot marks are defined in + addition to |*|, |x|, and |+| (the filling color has been set to a + dark yellow): + + \catcode`\|=12 + \medskip + \begin{tabular}{lc} + \plotmarkentry{-} + \index{*vbar@\protect\texttt{\protect\myvbar} plot mark}% + \index{Plot marks!*vbar@\protect\texttt{\protect\myvbar}} + \texttt{\char`\\pgfuseplotmark\char`\{\declare{|}\char`\}} & + \tikz\draw[color=black!25] plot[mark=|,mark options={fill=yellow,draw=black}] + coordinates {(0,0) (.5,0.2) (1,0) (1.5,0.2)};\\ + \plotmarkentry{o} + \plotmarkentry{asterisk} + \plotmarkentry{star} + \plotmarkentry{oplus} + \plotmarkentry{oplus*} + \plotmarkentry{otimes} + \plotmarkentry{otimes*} + \plotmarkentry{square} + \plotmarkentry{square*} + \plotmarkentry{triangle} + \plotmarkentry{triangle*} + \plotmarkentry{diamond} + \plotmarkentry{diamond*} + \plotmarkentry{pentagon} + \plotmarkentry{pentagon*} + \end{tabular} +\end{package} + + + +\subsection{Shape Library} + +\begin{package}{pgflibraryshapes} + This library packages defines additional shapes, which are + described in the following. +\end{package} + +\begin{shape}{cross out} + This shape ``crosses out'' the node. Its foreground path are simply + two diagonal lines that between the corners of the node's bounding + box. Here is an example: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \node [cross out,draw=red] at (1.5,1) {cross out}; +\end{tikzpicture} +\end{codeexample} + + A useful application is inside text as in the following example: +\begin{codeexample}[] +Cross \tikz[baseline] \node [cross out,draw,anchor=text] {me}; out! +\end{codeexample} + + This shape inherits all anchors from the |rectangle| shape, see also + the following figure: +\begin{codeexample}[] +\Huge +\begin{tikzpicture} + \node[name=s,shape=cross out,style=shape example] {cross out\vrule width 1pt height 2cm}; + \foreach \anchor/\placement in + {north west/above left, north/above, north east/above right, + west/left, center/above, east/right, + mid west/right, mid/above, mid east/left, + base west/left, base/below, base east/right, + south west/below left, south/below, south east/below right, + text/left, 10/right, 130/above} + \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)} + node[\placement] {\scriptsize\texttt{(s.\anchor)}}; +\end{tikzpicture} +\end{codeexample} +\end{shape} + +\begin{shape}{ellipse} + This shape is an ellipse tightly fitting the text box, if no inner + separation is given. The following figure shows the anchors this + shape defines; the anchors |10| and |130| are example of border anchors. +\begin{codeexample}[] +\Huge +\begin{tikzpicture} + \node[name=s,shape=ellipse,style=shape example] {Ellipse\vrule width 1pt height 2cm}; + \foreach \anchor/\placement in + {north west/above left, north/above, north east/above right, + west/left, center/above, east/right, + mid west/right, mid/above, mid east/left, + base west/left, base/below, base east/right, + south west/below left, south/below, south east/below right, + text/left, 10/right, 130/above} + \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)} + node[\placement] {\scriptsize\texttt{(s.\anchor)}}; +\end{tikzpicture} +\end{codeexample} +\end{shape} + +\begin{shape}{forbidden sign} + This shape places the node inside a circle with a diagonal from the + lower left to the upper right added. The circle is part of the + background, the diagonal line part of the foreground path; thus, the + diagonal line is on top of the text. + +\begin{codeexample}[] +\begin{tikzpicture} + \node [forbidden sign,line width=1ex,draw=red,fill=white] {Smoking}; +\end{tikzpicture} +\end{codeexample} + + The shape inherits all anchors from the |circle| shape, see also the + following figure: +\begin{codeexample}[] +\Huge +\begin{tikzpicture} + \node[name=s,shape=forbidden sign,style=shape example] {Forbidden\vrule width 1pt height 2cm}; + \foreach \anchor/\placement in + {north west/above left, north/above, north east/above right, + west/left, center/above, east/right, + mid west/right, mid/above, mid east/left, + base west/left, base/below, base east/right, + south west/below left, south/below, south east/below right, + text/left, 10/right, 130/above} + \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)} + node[\placement] {\scriptsize\texttt{(s.\anchor)}}; +\end{tikzpicture} +\end{codeexample} +\end{shape} + + +\begin{shape}{strike out} + This shape is idential to the |cross out| shape, only its foreground + path consists of a single line from the lower left to the upper + right. + +\begin{codeexample}[] +Strike \tikz[baseline] \node [strike out,draw,anchor=text] {me}; out! +\end{codeexample} + + See the |cross out| shape for the anchors. +\end{shape} + + + +\subsection{Tree Library} + +\label{section-tree-library} + + +\begin{package}{pgflibrarytikztrees} + This packages defines styles to be used when drawing trees. +\end{package} + +\subsubsection{Growth Functions} + +The package |pgflibrarytikztrees| defines two new growth +functions. They are installed using the following options: + +\begin{itemize} + \itemoption{grow via three points}|=one child at (|\meta{x}% + |) and two children at (|\meta{y}|) and (|\meta{z}|)| + This option installs a growth function that works as follows: If a + parent node has just one child, this child is placed at \meta{x}. If + the parent node has two children, these are placed at \meta{y} and + \meta{z}. If the parent node has more than two children, the + children are placed at points that are linearly extrapolated from + the three points \meta{x}, \meta{y}, and \meta{z}. In detail, the + position is $x + \frac{n-1}{2}(y-x) + (c-1)(z-y)$, where $n$ is the + number of children and $c$ is the number of the current child + (starting with~$1$). + + The net effect of all this is that if you have a certain ``linear + arrangement'' in mind and use this option to specify the placement + of a single child and of two children, then any number of children + will be placed correctly. + + Here are some arrangements based on this growth function. We start + with a simple ``above'' arrangement: +\begin{codeexample}[] +\begin{tikzpicture}[grow via three points={% + one child at (0,1) and two children at (-.5,1) and (.5,1)}] + \node at (0,0) {one} child; + \node at (0,-1.5) {two} child child; + \node at (0,-3) {three} child child child; + \node at (0,-4.5) {four} child child child child; +\end{tikzpicture} +\end{codeexample} + + The next arrangement places children above, but ``grows only to the + right.'' +\begin{codeexample}[] +\begin{tikzpicture}[grow via three points={% + one child at (0,1) and two children at (0,1) and (1,1)}] + \node at (0,0) {one} child; + \node at (0,-1.5) {two} child child; + \node at (0,-3) {three} child child child; + \node at (0,-4.5) {four} child child child child; +\end{tikzpicture} +\end{codeexample} + + In the final arrangement, the children are placed along a line going + down and right. +\begin{codeexample}[] +\begin{tikzpicture}[grow via three points={% + one child at (-1,-.5) and two children at (-1,-.5) and (0,-.75)}] + \node at (0,0) {one} child; + \node at (0,-1.5) {two} child child; + \node at (0,-3) {three} child child child; + \node at (0,-4.5) {four} child child child child; +\end{tikzpicture} +\end{codeexample} + + These examples should make it clear how you can create new styles to + arrange your children along a line. + + \itemstyle{grow cyclic} + This style causes the children to be arranged ``on a circle.'' For + this, the children are placed at distance |\tikzleveldistance| from + the parent node, but not on a straight line, but points on a + circle. Instead of a sibling distance, there is a |sibling angle| + that denotes the angle between two given children. + \begin{itemize} + \itemoption{sibling angle}|=|\meta{angle} + Sets the angle between siblings in the |grow cyclic| style. + \end{itemize} + Note that this function will rotate the coordinate system of the + children to ensure that the grandchildren will grow in the right + direction. +\begin{codeexample}[] +\begin{tikzpicture}[grow cyclic] + \tikzstyle{level 1}=[level distance=8mm,sibling angle=60] + \tikzstyle{level 2}=[level distance=4mm,sibling angle=45] + \tikzstyle{level 3}=[level distance=2mm,sibling angle=30] + \coordinate [rotate=-90] % going down + child foreach \x in {1,2,3} + {child foreach \x in {1,2,3} + {child foreach \x in {1,2,3}}}; +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +\subsubsection{Edges From Parent} + +The following styles can be used to modify how the edges from parents +are drawn: + +\begin{itemize} + \itemstyle{edge from parent fork down} + This style will draw a line from the parent downwards (for half the + level distance) and then on to the child using only horizontal and + vertical lines. +\begin{codeexample}[] +\begin{tikzpicture} + \node {root} + [edge from parent fork down] + child {node {left}} + child {node {right} + child[child anchor=north east] {node {child}} + child {node {child}} + }; +\end{tikzpicture} +\end{codeexample} + \itemstyle{edge from parent fork right} + This style behaves similarly, only it will first draw its edge to + the right. +\begin{codeexample}[] +\begin{tikzpicture} + \node {root} + [edge from parent fork right,grow=right] + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; +\end{tikzpicture} +\end{codeexample} + \itemstyle{edge from parent fork left} + behaves similary. + \itemstyle{edge from parent fork up} + behaves similary. +\end{itemize} + + + +\subsection{Background Library} + +\label{section-tikz-backgrounds} + +\begin{package}{pgflibrarytikzbackgrounds} + This packages defines ``backgrounds'' for pictures. This does not + refer to background pictures, but rather to frames drawn around and + behind pictures. For example, this package allows you to just add + the |framed| option to a picture to get a rectangular box around + your picture or |gridded| to put a grid behind your picture. +\end{package} + +When this package is loaded, the following styles become available: +\begin{itemize} + \itemstyle{show background rectangle} + This style causes a rectangle to be drawn behind your graphic. This + style option must be given to the |{tikzpicture}| environment or to + the |\tikz| command. +\begin{codeexample}[] +\begin{tikzpicture}[show background rectangle] + \draw (0,0) ellipse (10mm and 5mm); +\end{tikzpicture} +\end{codeexample} + The size of the background rectangle is determined as follows: + We start with the bounding box of the picture. Then, a certain + separator distance is added on the sides. This distance can be + different for the $x$- and $y$-directions and can be set using the + following options: + \begin{itemize} + \itemoption{inner frame xsep}|=|\meta{dimension} + Sets the additional horizontal separator distance for the + background rectangle. The default is |1ex|. + \itemoption{inner frame ysep}|=|\meta{dimension} + Same for the vertical separator distance. + \itemoption{inner frame sep}|=|\meta{dimension} + sets the horizontal and vertical separator distances + simultaneously. + \end{itemize} + The following two styles make setting the inner separator a bit + easier to remember: + \begin{itemize} + \itemstyle{tight background} Sets the inner frame separator to + 0pt. The background rectangle will have the size of the bounding + box. + \itemstyle{loose background} Sets the inner frame separator to 2ex. + \end{itemize} + + You can influence how the background rectangle is rendered by setting + the following style: + \begin{itemize} + \itemstyle{background rectangle} + This style dictates how the background rectangle is drawn or + filled. By default this style is set to |draw|, which causes the + path of the background rectangle to be drawn in the usual + way. Setting this style to, say, |fill=blue!20| causes a light + blue background to be added to the picture. You can also use more + fancy settings as shown in the following example: +\begin{codeexample}[] +\tikzstyle{background rectangle}= + [double,ultra thick,draw=red,top color=blue,rounded corners] +\begin{tikzpicture}[show background rectangle] + \draw (0,0) ellipse (10mm and 5mm); +\end{tikzpicture} +\end{codeexample} + Naturally, no one in their right mind would use the above, but + here is a nice background: +\begin{codeexample}[] +\tikzstyle{background rectangle}= + [draw=blue!50,fill=blue!20,rounded corners=1ex] +\begin{tikzpicture}[show background rectangle] + \draw (0,0) ellipse (10mm and 5mm); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + \itemstyle{framed} + This is a shorthand for |show background rectangle|. + \itemstyle{show background grid} + This style behaves similarly to the |show background rectangle| + style, but it will not use a rectangle path, but a grid. The lower + left and upper right corner of the grid is computed in the same way + as for the background rectangle: +\begin{codeexample}[] +\begin{tikzpicture}[show background grid] + \draw (0,0) ellipse (10mm and 5mm); +\end{tikzpicture} +\end{codeexample} + You can influence the background grid by setting + the following style: + \begin{itemize} + \itemstyle{background grid} + This style dictates how the background grid path is drawn. The + default is |draw,help lines|. +\begin{codeexample}[] +\tikzstyle{background grid}=[thick,draw=red,step=.5cm] +\begin{tikzpicture}[show background grid] + \draw (0,0) ellipse (10mm and 5mm); +\end{tikzpicture} +\end{codeexample} + This option can be combined with the |framed| option (use the + |framed| option first): +\begin{codeexample}[] +\tikzstyle{background grid}=[thick,draw=red,step=.5cm] +\tikzstyle{background rectangle}=[rounded corners,fill=yellow] +\begin{tikzpicture}[framed,gridded] + \draw (0,0) ellipse (10mm and 5mm); +\end{tikzpicture} +\end{codeexample} + \itemstyle{gridded} + This is a shorthand for |show background grid|. + \end{itemize} + \itemstyle{show background top} + This style causes a single line to be drawn at the top of the + background rectangle. Normally, the line coincides exactly with the + top line of the background rectangle: +\begin{codeexample}[] +\tikzstyle{background rectangle}=[fill=yellow] +\begin{tikzpicture}[framed,show background top] + \draw (0,0) ellipse (10mm and 5mm); +\end{tikzpicture} +\end{codeexample} + The following option allows you to lengthen (or shorten) the line: + \begin{itemize} + \itemoption{outer frame xsep}|=|\meta{dimension} + The \meta{dimension} is added at the left and right side of the + line. +\begin{codeexample}[] +\tikzstyle{background rectangle}=[fill=yellow] +\begin{tikzpicture} + [framed,show background top,outer frame xsep=1ex] + \draw (0,0) ellipse (10mm and 5mm); +\end{tikzpicture} +\end{codeexample} + \itemoption{outer frame ysep}|=|\meta{dimension} + This option does not apply to the top line, but to the left and + right lines, see below. + \itemoption{outer frame sep}|=|\meta{dimension} + Sets both the $x$- and $y$-separation. +\begin{codeexample}[] +\tikzstyle{background rectangle}=[fill=blue!20] +\begin{tikzpicture} + [outer frame sep=1ex,% + show background top,% + show background bottom,% + show background left,% + show background right] + \draw (0,0) ellipse (10mm and 5mm); +\end{tikzpicture} +\end{codeexample} + \end{itemize} + You can influence how the line is drawn grid by setting + the following style: + \begin{itemize} + \itemstyle{background top} + Default is |draw|. +\begin{codeexample}[] +\tikzstyle{background rectangle}=[fill=blue!20] +\tikzstyle{background top}=[draw=blue!50,line width=1ex] +\begin{tikzpicture}[framed,show background top] + \draw (0,0) ellipse (10mm and 5mm); +\end{tikzpicture} +\end{codeexample} + \end{itemize} + \itemstyle{show background bottom} + works like the style for the top line. + \itemstyle{show background left} + works like the style for the top line. + \itemstyle{show background right} + works like the style for the top line. +\end{itemize} + + +\subsection{Automata Drawing Library} + +\begin{package}{pgflibraryautomata} + This packages, which is still under construction, provides shapes + and styles for drawing automata. +\end{package} + + +\begin{shape}{state} + This shape is currently just an alias for the |circle| + shape. However, it is useful to have another shape |state| since one + can then say, for example, the the style |every state shape| should + be set to some special value. +\end{shape} + +\begin{shape}{state with output} + This shape is a multi-part shape. The main part (the text part) is + the name of the state as in the |state| shape. The second part is + called |output|. This node part is drawn in the lower part of the + node, separated from the upper part by a line. + +\begin{codeexample}[] +\begin{tikzpicture} + \node [state with output,draw,double,fill=red!20] + { + $q_1$ + \nodepart{output} + $00$ + }; +\end{tikzpicture} +\end{codeexample} + + The shape inherits all anchors from the |circle| shape and defines + the |output| anchor in addition. See also the + following figure: +\begin{codeexample}[] +\Huge +\begin{tikzpicture} + \node[name=s,shape=state with output,style=shape example] {state name\nodepart{output}output}; + \foreach \anchor/\placement in + {north west/above left, north/above, north east/above right, + west/left, center/below, east/right, + mid west/right, mid/above, mid east/left, + base west/left, base/below, base east/right, + south west/below left, south/below, south east/below right, + text/left, output/left, 130/above} + \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)} + node[\placement] {\scriptsize\texttt{(s.\anchor)}}; +\end{tikzpicture} +\end{codeexample} +\end{shape} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-license.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-license.tex new file mode 100644 index 00000000000..16b158e11a2 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-license.tex @@ -0,0 +1,326 @@ +% $Header: /cvsroot/pgf/pgf/doc/pgf/text-en/pgfmanual-en-license.tex,v 1.1 2005/09/02 16:05:42 tantau Exp $ + +% Copyright 2003, 2004 by Till Tantau <tantau@users.sourceforge.net>. +% +% This program can be redistributed and/or modified under the terms +% of the GNU Public License, version 2. + + +\subsection{License: The GNU Public License, Version 2} +\label{section-license} + +The \pgfname\ package is distributed under the \textsc{gnu} public +license, version 2. In detail, this means the following (the following +text is copyrighted by the Free Software Foundation): + +\subsubsection{Preamble} + +The licenses for most software are designed to take away your freedom to +share and change it. By contrast, the \textsc{gnu} General Public License is +intended to guarantee your freedom to share and change free software---to +make sure the software is free for all its users. This General Public +License applies to most of the Free Software Foundation's software and to +any other program whose authors commit to using it. (Some other Free +Software Foundation software is covered by the \textsc{gnu} Library General Public +License instead.) You can apply it to your programs, too. + +When we speak of free software, we are referring to freedom, not price. +Our General Public Licenses are designed to make sure that you have the +freedom to distribute copies of free software (and charge for this service +if you wish), that you receive source code or can get it if you want it, +that you can change the software or use pieces of it in new free programs; +and that you know you can do these things. + +To protect your rights, we need to make restrictions that forbid anyone to +deny you these rights or to ask you to surrender the rights. These +restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + +For example, if you distribute copies of such a program, whether gratis or +for a fee, you must give the recipients all the rights that you have. You +must make sure that they, too, receive or can get the source code. And +you must show them these terms so they know their rights. + +We protect your rights with two steps: (1) copyright the software, and (2) +offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + +Also, for each author's protection and ours, we want to make certain that +everyone understands that there is no warranty for this free software. If +the software is modified by someone else and passed on, we want its +recipients to know that what they have is not the original, so that any +problems introduced by others will not reflect on the original authors' +reputations. + +Finally, any free program is threatened constantly by software patents. +We wish to avoid the danger that redistributors of a free program will +individually obtain patent licenses, in effect making the program +proprietary. To prevent this, we have made it clear that any patent must +be licensed for everyone's free use or not licensed at all. + +The precise terms and conditions for copying, distribution and +modification follow. + +\subsubsection{Terms and Conditions For Copying, Distribution and + Modification} + +\begin{enumerate} + +\addtocounter{enumi}{-1} + +\item +This License applies to any program or other work which contains a notice +placed by the copyright holder saying it may be distributed under the +terms of this General Public License. The ``Program'', below, refers to +any such program or work, and a ``work based on the Program'' means either +the Program or any derivative work under copyright law: that is to say, a +work containing the Program or a portion of it, either verbatim or with +modifications and/or translated into another language. (Hereinafter, +translation is included without limitation in the term ``modification''.) +Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +\item You may copy and distribute verbatim copies of the Program's source + code as you receive it, in any medium, provided that you conspicuously + and appropriately publish on each copy an appropriate copyright notice + and disclaimer of warranty; keep intact all the notices that refer to + this License and to the absence of any warranty; and give any other + recipients of the Program a copy of this License along with the Program. + +You may charge a fee for the physical act of transferring a copy, and you +may at your option offer warranty protection in exchange for a fee. + +\item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +\begin{enumerate} + +\item +You must cause the modified files to carry prominent notices stating that +you changed the files and the date of any change. + +\item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +\item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) + +\end{enumerate} + + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +\item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +\begin{enumerate} + +\item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +\item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +\item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsubsection b above.) + +\end{enumerate} + + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +\item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +\item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +\item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +\item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +\item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +\item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +\item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +\end{enumerate} + +\subsubsection{No Warranty} + +\begin{enumerate} + +\addtocounter{enumi}{9} + +\item +Because the program is licensed free of charge, there is no warranty +for the program, to the extent permitted by applicable law. Except when +otherwise stated in writing the copyright holders and/or other parties +provide the program ``as is'' without warranty of any kind, either expressed +or implied, including, but not limited to, the implied warranties of +merchantability and fitness for a particular purpose. The entire risk as +to the quality and performance of the program is with you. Should the +program prove defective, you assume the cost of all necessary servicing, +repair or correction. + +\item +In no event unless required by applicable law or agreed to in writing +will any copyright holder, or any other party who may modify and/or +redistribute the program as permitted above, be liable to you for damages, +including any general, special, incidental or consequential damages arising +out of the use or inability to use the program (including but not limited +to loss of data or data being rendered inaccurate or losses sustained by +you or third parties or a failure of the program to operate with any other +programs), even if such holder or other party has been advised of the +possibility of such damages. +\end{enumerate} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "beameruserguide" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex new file mode 100644 index 00000000000..992375bc778 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex @@ -0,0 +1,352 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + +% pgf version is defined in \pgfversion in file +% generic/pgf/utilities/pgfrcs.code.tex + +\def\xcolorversion{2.00} +\def\xkeyvalversion{1.8} + +\usepackage[version=0.96]{pgf} +\usepackage{tikz} +\usepackage{pgflibraryarrows} +\usepackage{pgflibraryshapes} +\usepackage{pgflibrarysnakes} +\usepackage{pgflibraryautomata} +\usepackage{pgflibraryplotmarks} +\usepackage{pgflibrarytikzbackgrounds} +\usepackage{pgflibrarytikztrees} +\usepackage[left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry} +\usepackage{amsmath,amssymb} +\usepackage{xxcolor} +\usepackage{pifont} +\usepackage{makeidx} +\usepackage[latin1]{inputenc} +\usepackage{amsmath} + +\input{../../macros/pgfmanual-en-macros} + +\makeindex + +\makeatletter +\renewcommand*\l@subsection{\@dottedtocline{2}{1.5em}{2.8em}} +\renewcommand*\l@subsubsection{\@dottedtocline{3}{4.3em}{3.2em}} +\makeatother + +%\includeonly{pgfmanual-en-tikz-shapes} + +% Global styles: +\tikzstyle{every plot}=[prefix=plots/pgf-] +\tikzstyle{shape example}=[color=black!30,draw,fill=yellow!30,line width=.5cm,inner xsep=2.5cm,inner ysep=0.5cm] + +\index{Options for graphics|see{Graphic options}} +\index{Options for packages|see{Package options}} +\index{File|see{Packages and files}} +\index{Layout|see{Page layout}} + +\begin{document} + +{ + \parindent0pt +\vbox{} +\vskip 3.5cm +\Huge +\tikzname\ and \pgfname + +\Large +Manual for Version \pgfversion + +\vskip 3cm + +\begin{codeexample}[graphic=white] +\tikzstyle{level 1}=[sibling angle=120] +\tikzstyle{level 2}=[sibling angle=60] +\tikzstyle{level 3}=[sibling angle=30] +\tikzstyle{every node}=[fill] +\tikzstyle{edge from parent}=[snake=expanding waves,segment length=1mm,segment angle=10,draw] + +\tikz [grow cyclic,shape=circle,very thick,level distance=13mm,cap=round] + \node {} child [color=\A] foreach \A in {red,green,blue} + { node {} child [color=\A!50!\B] foreach \B in {red,green,blue} + { node {} child [color=\A!50!\B!50!\C] foreach \C in {black,gray,white} + { node {} } + } + }; +\end{codeexample} +\vskip 0cm plus 1.5fill +\vbox{} +\clearpage +} + +{ + \vbox{} + \vskip0pt plus 1fill + Für meinen Vater, damit er noch viele schöne \TeX-Graphiken erschaffen kann. + \vskip0pt plus 3fill + \vbox{} + \clearpage +} + + +\title{The \tikzname\ and \pgfname\ Packages\\ + Manual for Version \pgfversion\\[1mm] +\large\href{http://sourceforge.net/projects/pgf}{\texttt{http://sourceforge.net/projects/pgf}}} +\author{Till Tantau\\ + \href{mailto:tantau@users.sourceforge.net}{\texttt{tantau@users.sourceforge.net}}} + +\maketitle + +\tableofcontents + +\clearpage + +\part{Getting Started} + +This part is intended to help you get started with the \pgfname\ +package. First, the installation process is explained; however, the +system will typically be already installed on your system, so this can +often be skipped. Next, a short tutorial is given that explains the +most often used commands and concepts of \tikzname, without going into +any of the glorious details. At the end of this section you will find +some, hopefully useful, hints on how to create ``good'' graphics in +general. The information in this section is not specific to +\pgfname. + +\vskip3cm + +\begin{codeexample}[graphic=white,width=0pt] +\tikz \draw[thick,rounded corners=8pt] + (0,0) -- (0,2) -- (1,3.25) -- (2,2) -- (2,0) -- (0,2) -- (2,2) -- (0,0) -- (2,0); +\end{codeexample} + +\include{pgfmanual-en-introduction} +\include{pgfmanual-en-installation} +\include{pgfmanual-en-tutorial} +\include{pgfmanual-en-guidelines} +\include{pgfmanual-en-drivers} + + +\part{Ti\emph{k}Z ist \emph{kein} Zeichenprogramm} +\label{part-tikz} + +\vskip3cm +\begin{codeexample}[graphic=white] +\begin{tikzpicture} + \draw[fill=yellow] (0,0) -- (60:.75cm) arc (60:180:.75cm); + \draw(120:0.4cm) node {$\alpha$}; + + \draw[fill=green!30] (0,0) -- (right:.75cm) arc (0:60:.75cm); + \draw(30:0.5cm) node {$\beta$}; + + \begin{scope}[shift={(60:2cm)}] + \draw[fill=green!30] (0,0) -- (180:.75cm) arc (180:240:.75cm); + \draw (30:-0.5cm) node {$\gamma$}; + + \draw[fill=yellow] (0,0) -- (240:.75cm) arc (240:360:.75cm); + \draw (-60:0.4cm) node {$\delta$}; + \end{scope} + + \begin{scope}[thick] + \draw (60:-1cm) node[fill=white] {$E$} -- (60:3cm) node[fill=white] {$F$}; + \draw[red] (-2,0) node[left] {$A$} -- (3,0) node[right]{$B$}; + \draw[blue,shift={(60:2cm)}] (-3,0) node[left] {$C$} -- (2,0) node[right]{$D$}; + + \draw[shift={(60:1cm)},xshift=4cm] + node [right,text width=6cm,rounded corners,fill=red!20,inner sep=1ex] + { + When we assume that $\color{red}AB$ and $\color{blue}CD$ are + parallel, i.\,e., ${\color{red}AB} \mathbin{\|} \color{blue}CD$, + then $\alpha = \delta$ and $\beta = \gamma$. + }; + \end{scope} +\end{tikzpicture} +\end{codeexample} + + + +\include{pgfmanual-en-tikz-design} +\include{pgfmanual-en-tikz-scopes} +\include{pgfmanual-en-tikz-coordinates} +\include{pgfmanual-en-tikz-paths} +\include{pgfmanual-en-tikz-actions} +\include{pgfmanual-en-tikz-shapes} +\include{pgfmanual-en-tikz-trees} +\include{pgfmanual-en-tikz-transformations} + + + +\part{Libraries and Utilities} +\label{part-libraries} + +In this part the library and utility packages are documented. The +library packages provide additional predefined graphic objects like +new arrow heads, or new plot marks. These are not loaded by default +since many users will not need them. + +The utility packages are not directly involved in creating graphics, +but you may find them useful nonetheless. All of them either directly +depend on \pgfname\ or they are designed to work well together with +\pgfname\ even though they can be used in a stand-alone way. +\vskip2cm +\medskip +\noindent +\begin{codeexample}[graphic=white] +\begin{tikzpicture}[scale=2] + \shade[top color=blue,bottom color=gray!50] (0,0) parabola (1.5,2.25) |- (0,0); + \draw (1.05cm,2pt) node[above] {$\displaystyle\int_0^{3/2} \!\!x^2\mathrm{d}x$}; + + \draw[style=help lines] (0,0) grid (3.9,3.9) + [step=0.25cm] (1,2) grid +(1,1); + + \draw[->] (-0.2,0) -- (4,0) node[right] {$x$}; + \draw[->] (0,-0.2) -- (0,4) node[above] {$f(x)$}; + + \foreach \x/\xtext in {1/1, 1.5/1\frac{1}{2}, 2/2, 3/3} + \draw[shift={(\x,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\xtext$}; + + \foreach \y/\ytext in {1/1, 2/2, 2.25/2\frac{1}{4}, 3/3} + \draw[shift={(0,\y)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\ytext$}; + + \draw (-.5,.25) parabola bend (0,0) (2,4) node[below right] {$x^2$}; +\end{tikzpicture} +\end{codeexample} + +\include{pgfmanual-en-libraries} +\include{pgfmanual-en-pgffor} +\include{pgfmanual-en-pages} +\include{pgfmanual-en-xxcolor} + + + +\part{The Basic Layer} + +\vskip1cm +\begin{codeexample}[graphic=white] +\begin{tikzpicture} + \draw[gray,very thin] (-1.9,-1.9) grid (2.9,3.9) + [step=0.25cm] (-1,-1) grid (1,1); + \draw[blue] (1,-2.1) -- (1,4.1); % asymptote + + \draw[->] (-2,0) -- (3,0) node[right] {$x(t)$}; + \draw[->] (0,-2) -- (0,4) node[above] {$y(t)$}; + + \foreach \pos in {-1,2} + \draw[shift={(\pos,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\pos$}; + + \foreach \pos in {-1,1,2,3} + \draw[shift={(0,\pos)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\pos$}; + + \fill (0,0) circle (0.064cm); + \draw[thick,parametric,domain=0.4:1.5,samples=200] + % The plot is reparameterised such that there are more samples + % near the center. + plot[id=asymptotic-example] function{(t*t*t)*sin(1/(t*t*t)),(t*t*t)*cos(1/(t*t*t))} + node[right] {$\bigl(x(t),y(t)\bigr) = (t\sin \frac{1}{t}, t\cos \frac{1}{t})$}; + + \fill[red] (0.63662,0) circle (2pt) + node [below right,fill=white,yshift=-4pt] {$(\frac{2}{\pi},0)$}; +\end{tikzpicture} +\end{codeexample} + + +\include{pgfmanual-en-base-design} +\include{pgfmanual-en-base-scopes} +\include{pgfmanual-en-base-points} +\include{pgfmanual-en-base-paths} +\include{pgfmanual-en-base-snakes} +\include{pgfmanual-en-base-actions} +\include{pgfmanual-en-base-arrows} +\include{pgfmanual-en-base-nodes} +\include{pgfmanual-en-base-transformations} +\include{pgfmanual-en-base-images} +\include{pgfmanual-en-base-shadings} +\include{pgfmanual-en-base-plots} +\include{pgfmanual-en-base-layers} +\include{pgfmanual-en-base-quick} + + + + +\part{The System Layer} +\label{part-system} + +This part describes the low-level interface of \pgfname, called the +\emph{system layer}. This interface provides a complete abstraction of +the internals of the underlying drivers. + +Unless you intend to port \pgfname\ to another driver or unless you intend +to write your own optimized frontend, you need not read this part. + +In the following it is assumed that you are familiar with the basic +workings of the |graphics| package and that you know what +\TeX-drivers are and how they work. + +\vskip1cm +\begin{codeexample}[graphic=white] +\begin{tikzpicture}[shorten >=1pt,->] + \tikzstyle{vertex}=[circle,fill=black!25,minimum size=17pt,inner sep=0pt] + + \foreach \name/\x in {s/1, 2/2, 3/3, 4/4, 15/11, 16/12, 17/13, 18/14, 19/15, t/16} + \node[vertex] (G-\name) at (\x,0) {$\name$}; + + \foreach \name/\angle/\text in {P-1/234/5, P-2/162/6, P-3/90/7, P-4/18/8, P-5/-54/9} + \node[vertex,xshift=6cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$}; + + \foreach \name/\angle/\text in {Q-1/234/10, Q-2/162/11, Q-3/90/12, Q-4/18/13, Q-5/-54/14} + \node[vertex,xshift=9cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$}; + + \foreach \from/\to in {s/2,2/3,3/4,3/4,15/16,16/17,17/18,18/19,19/t} + \draw (G-\from) -- (G-\to); + + \foreach \from/\to in {1/2,2/3,3/4,4/5,5/1,1/3,2/4,3/5,4/1,5/2} + { \draw (P-\from) -- (P-\to); \draw (Q-\from) -- (Q-\to); } + + \draw (G-3) .. controls +(-30:2cm) and +(-150:1cm) .. (Q-1); + \draw (Q-5) -- (G-15); +\end{tikzpicture} +\end{codeexample} + +\include{pgfmanual-en-pgfsys-overview} +\include{pgfmanual-en-pgfsys-commands} +\include{pgfmanual-en-pgfsys-paths} +\include{pgfmanual-en-pgfsys-protocol} + + + +\part{References and Index} + +\vskip1cm +\begin{codeexample}[graphic=white] +\begin{tikzpicture} + \draw[line width=0.3cm,color=red!30,cap=round,join=round] (0,0)--(2,0)--(2,5); + \draw[help lines] (-2.5,-2.5) grid (5.5,7.5); + \draw[very thick] (1,-1)--(-1,-1)--(-1,1)--(0,1)--(0,0)-- + (1,0)--(1,-1)--(3,-1)--(3,2)--(2,2)--(2,3)--(3,3)-- + (3,5)--(1,5)--(1,4)--(0,4)--(0,6)--(1,6)--(1,5) + (3,3)--(4,3)--(4,5)--(3,5)--(3,6) + (3,-1)--(4,-1); + \draw[below left] (0,0) node(s){$s$}; + \draw[below left] (2,5) node(t){$t$}; + \fill (0,0) circle (0.06cm) (2,5) circle (0.06cm); + \draw[->,rounded corners=0.2cm,shorten >=2pt] + (1.5,0.5)-- ++(0,-1)-- ++(1,0)-- ++(0,2)-- ++(-1,0)-- ++(0,2)-- ++(1,0)-- + ++(0,1)-- ++(-1,0)-- ++(0,-1)-- ++(-2,0)-- ++(0,3)-- ++(2,0)-- ++(0,-1)-- + ++(1,0)-- ++(0,1)-- ++(1,0)-- ++(0,-1)-- ++(1,0)-- ++(0,-3)-- ++(-2,0)-- + ++(1,0)-- ++(0,-3)-- ++(1,0)-- ++(0,-1)-- ++(-6,0)-- ++(0,3)-- ++(2,0)-- + ++(0,-1)-- ++(1,0); +\end{tikzpicture} +\end{codeexample} + +\printindex + +\end{document} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "~/texmf/tex/generic/pgf/doc/pgf/version-for-pdftex/en/pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex new file mode 100644 index 00000000000..3b6480b4f8e --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex @@ -0,0 +1,670 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Page Management} + +This section describes the |pgfpages| packages. Although this package +is not concerned with creating pictures, its implementation relies so +heavily on \pgfname\ that it is documented here. Currently, |pgfpages| +only works with \LaTeX, but if you are adventurous, feel free to hack +the code so that it also works with plain \TeX. + +The aim of |pgfpages| is to provide a flexible way of putting multiple +pages on a single page \emph{inside \TeX}. Thus, |pgfpages| is quite +different from useful tools like |psnup| or |pdfnup| insofar as it +creates its output in a single pass. Furthermore, it works uniformly +with both |latex| and |pdflatex|, making it easy to put multiple pages +on a single page without any fuss. + +A word of warning: \emph{using |pgfpages| will destroy + hyperlinks}. Actually, the hyperlinks are not destroyed, only they +will appear at totally wrong positions on the final output. This is +due to a fundamental flaw in the \pdf\ specification: In \pdf\ the +bounding rectangle of a hyperlink is given in ``absolute +page coordinates'' and translations or rotations do not affect +them. Thus, the transformations applied by |pgfpages| to put the pages +where you want them are (cannot, even) be applied to the coordinates +of hyperlinks. It is unlikely that this will change in the foreseeable +future. + + +\subsection{Basic Usage} + +The internals of |pgfpages| are complex since the package can do all +sorts of interesting tricks. For this reason, so-called \emph{layouts} +are predefined that setup all option in appropriate ways. + +You use a layout as follows: +\begin{codeexample}[code only] +\documentclass{article} + +\usepackage{pgfpages} +\pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm] + +\begin{document} +This text is shown on the left. +\clearpage +This text is shown on the right. +\end{document} +\end{codeexample} + +The layout |2 on 1| puts two pages on a single page. The option +|a4paper| tells |pgfpages| that the \emph{resulting} page (called the +\emph{physical} page in the following) should be |a4paper| and it +should be landscape (which is quite logical since putting two portrait +pages next to each other gives a landscape page). Normally, the +\emph{logical} pages, that is, the pages that \TeX\ ``thinks'' that it +is typesetting, will have the same sizes, but this need not be the +case. |pgfpages| will automatically scale down the logical pages such +that two logical pages fit next to each other inside a DIN A4 page. + +The |border shrink| tells |pgfpages| that it should add an additional +5mm to the shrinking such that a 5mm-wide border is shown around the +resulting logical pages. + +As a second example, let us put two pages produced by the +\textsc{beamer} class on a single page: + +\begin{codeexample}[code only] +\documentclass{beamer} + +\usepackage{pgfpages} +\pgfpagesuselayout{2 on 1}[a4paper,border shrink=5mm] + +\begin{document} +\begin{frame} + This text is shown at the top. +\end{frame} +\begin{frame} + This text is shown at the bottom. +\end{frame} +\end{document} +\end{codeexample} + +Note that we do not use the |landscape| option since \textsc{beamer}'s +logical pages are already in landscape mode and putting two landscape +pages on top of each other results in a portrait page. However, if you +had used the |4 on 1| layout, you would have had to add |landscape| +once more, using the |8 on 1| you must not, using |16 on 1| you need +it yet again. And, no, there is no |32 on 1| layout. + +Another word of caution: \emph{using |pgfpages| will produce wrong + page numbers in the |.aux| file}. The reason is that \TeX\ +instantiates the page numbers when writing an |.aux| file only when +the physical page is shipped out. Fortunately, this problem is easy to +fix: First, typeset our file normally without using the +|\pgfpagesuselayout| command (just put the comment marker |%| before it) +Then, rerun \TeX\ with the |\pgfpagesuselayout| command included and add +the command |\nofiles|. This command ensures that the |.aux| file is +not modified, which is exactly what you want. So, to typeset the above +example, you should actually first \TeX\ the following file: + +\begin{codeexample}[code only] +\documentclass{article} + +\usepackage{pgfpages} +%%\pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm] +%%\nofiles + +\begin{document} +This text is shown on the left. +\clearpage +This text is shown on the right. +\end{document} +\end{codeexample} +and then typeset +\begin{codeexample}[code only] +\documentclass{article} + +\usepackage{pgfpages} +\pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm] +\nofiles + +\begin{document} +This text is shown on the left. +\clearpage +This text is shown on the right. +\end{document} +\end{codeexample} + +The final basic example is the |resize to| layout (it works a bit like +a hypothetical |1 on 1| layout). This layout resizes the logical page +such that is fits the specified physical size. Since this does not +change the page numbering, you need not worry about the |.aux| files +with this layout. For example, adding the following lines will ensure +that the physical output will fit on DIN A4 paper: +\begin{codeexample}[code only] +\usepackage{pgfpages} +\pgfpagesuselayout{resize to}[a4paper] +\end{codeexample} + +This can be very useful when you have to handle lots of papers that +are typeset for, say, letter paper and you have an A4 printer or the +other way round. For example, the following article will be fit for +printing on letter paper: +\begin{codeexample}[code only] +\documentclass[a4paper]{article} +%% a4 is currently the logical size and also the physical size + +\usepackage{pgfpages} +\pgfpagesuselayout{resize to}[letterpaper] +%% a4 is still the logical size, but letter is the physical one + +\begin{document} + \title{My Great Article} +... +\end{document} +\end{codeexample} + + + +\subsection{The Predefined Layouts} + +This section explains the predefined layouts in more detail. You +select a layout using the following command: +\begin{command}{\pgfpagesuselayout\marg{layout}\oarg{options}} + Installs the specified \meta{layout} with the given \meta{options} + set. The predefined layouts and their permissible options are + explained below. + + If this function is called multiple times, only the last call + ``wins.'' You can thereby overwrite any previous settings. In + particular, layouts \emph{do not} accumulate. + + \example |\pgfpagesuselayout{resize to}[a4paper]| +\end{command} + +\begin{pgflayout}{resize to} + This layout is used to resize every logical page to a specified + physical size. To determine the target size, the following options + may be given: + \begin{itemize} + \item + \declare{|physical paper height=|\meta{size}} sets the + height of the physical pape size to \meta{size}. + \item + \declare{|physical paper width=|\meta{size}} sets the + width of the physical pape size to \meta{size}. + \item + \declare{|a0paper|} sets the physical page size to DIN A0 paper. + \item + \declare{|a1paper|} sets the physical page size to DIN A1 paper. + \item + \declare{|a2paper|} sets the physical page size to DIN A2 paper. + \item + \declare{|a3paper|} sets the physical page size to DIN A3 paper. + \item + \declare{|a4paper|} sets the physical page size to DIN A4 paper. + \item + \declare{|a5paper|} sets the physical page size to DIN A5 paper. + \item + \declare{|a6paper|} sets the physical page size to DIN A6 paper. + \item + \declare{|letterpaper|} sets the physical page size to the + American letter paper size. + \item + \declare{|legalpaper|} sets the physical page size to the + American legal paper size. + \item + \declare{|executivepaper|} sets the physical page size to the + American executive paper size. + \item + \declare{|landscape|} swaps the height and the width of the + physical paper. + \item + \declare{|border shrink=|\meta{size}} additionally reduces the + size of the logical page on the physical page by \meta{size}. + \end{itemize} +\end{pgflayout} + +\begin{pgflayout}{2 on 1} + Puts two logical pages alongside each other on each physical page if + the logical height is larger than the logical width (logical pages + are in portrait mode). Otherwise, two + logical pages are put on top of each other (logical pages are in + landscape mode). When using this layout, it is advisable to use the + |\nofiles| command, but this is not done automatically. + + The same \meta{options} as for the |resize to| layout an be used, + plus the following option: + \begin{itemize} + \item + \declare{|odd numbered pages right|} + places the first page on the right. + \end{itemize} +\end{pgflayout} + + +\begin{pgflayout}{4 on 1} + Puts four logical pages on a single physical page. + The same \meta{options} as for the |resize to| layout an be used. +\end{pgflayout} + +\begin{pgflayout}{8 on 1} + Puts eight logical pages on a single physical page. As for |2 on 1|, + the orientation depends on whether the logical pages are in + landscape mode or in portrait mode. +\end{pgflayout} + +\begin{pgflayout}{16 on 1} + This is for the \textsc{ceo}. +\end{pgflayout} + +\begin{pgflayout}{rounded corners} + \label{layout-rounded-corners} + This layout adds ``rounded corners'' to every page, which, + supposedly, looks nicer during presentations with projectors + (personally, I doubt this). This is done by (possibly) resizing the + page to the physical page size. Then four black rectangles are + drawn in each corner. Next, a clipping region is set up that + contains all of the logical page except for little rounded + corners. Finally, the logical page is draw, clipped against the + clipping region. + + Note that every logical page should fill its background for this to + work. + + In addition to the \meta{options} that can be given to |resize to| + the following options may be given. + \begin{itemize} + \item \declare{|corner width=|\meta{size}} specifies the size of + the corner. + \end{itemize} + + \begin{codeexample}[code only] +\documentclass{beamer} +\usepackage{pgfpages} +\pgfpagesuselayout{rounded corners}[corner width=5pt] +\begin{document} +... +\end{document} +\end{codeexample} +\end{pgflayout} + +\begin{pgflayout}{two screens with lagging second} + This layout puts two logical pages alongside each other. The second + page always shows what the main + page showed on the previous physical page. Thus, the second page + ``lags behind'' the main page. This can be useful when you have to + projectors attached to your computer and can show different parts of + a physical page on different projectors. + + The following \meta{options} may be given: + \begin{itemize} + \item \declare{|second right|} puts the second page right of the + main page. This will make the physical pages twice as wide + as the logical pages, but it will retain the height. + \item \declare{|second left|} puts the second page left, + otherwise it behave the same as |second right|. + \item \declare{|second bottom|} puts the second page below the main + page. This make the physical pages twice as high as the logical + ones. + \item \declare{|second top|} works like |second bottom|. + \end{itemize} +\end{pgflayout} + +\begin{pgflayout}{two screens with optional second} + This layout works similarly to + |two screens with lagging second|. The difference is that the + contents of the second screen only changes when one of the commands + |\pgfshipoutlogicalpage{2}|\marg{box} or + |\pgfcurrentpagewillbelogicalpage{2}| is called. The first puts the + given \meta{box} on the second page. The second specifies that the + current page should be put there, once it is finished. + + The same options as for |two screens with lagging second| may be + given. +\end{pgflayout} + + + +You can define your own predefined layouts using the following +command: + +\begin{command}{\pgfpagesdeclarelayout\marg{layout}\marg{before + actions}\marg{after actions}} + This command predefines a \meta{layout} that can later be installed + using the |\pgfpagesuselayout| command. + + When |\pgfpagesuselayout|\marg{layout}\oarg{options} is called, the + following happens: First, the \meta{before actions} are + executed. They can be used, for example, to setup default values for + keys. Next, |\setkeys{pgfpagesuselayoutoption}|\marg{options} is + executed. Finally, the \meta{after actions} are executed. + + Here is an example: +\begin{codeexample}[code only] +\pgfpagesdeclarelayout{resize to} +{ + \def\pgfpageoptionborder{0pt} +} +{ + \pgfpagesphysicalpageoptions + {% + logical pages=1,% + physical height=\pgfpageoptionheight,% + physical width=\pgfpageoptionwidth% + } + \pgfpageslogicalpageoptions{1} + {% + resized width=\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% + border shrink=\pgfpageoptionborder,% + center=\pgfpoint{.5\pgfphysicalwidth}{.5\pgfphysicalheight}% + }% +} +\end{codeexample} +\end{command} + + + + +\subsection{Defining a Layout} + +If none of the predefined layouts meets your problem or if you wish to +modify them, you can create layouts from scratch. This section +explains how this is done. + +Basically, |pgfpages| hooks into \TeX's |\shipout| function. This +function is called whenever \TeX\ has completed typesetting a page and +wishes to send this page to the |.dvi| or |.pdf| file. The |pgfpages| +package redefines this command. Instead of sending the page to the output +file, |pgfpages| stores it in an internal box and then acts as if the +page had been output. When \TeX\ tries to output the next page using +|\shipout|, this call is once more intercepted and the page is stored +in another box. These boxes are called \emph{logical pages}. + +At some point, enough logical pages have been accumulated such that a +\emph{physical page} can be output. When this happens, |pgfpages| +possibly scales, rotates, and translates the logical pages (and +possibly even does further modifications) and then puts them at +certain positions of the \emph{physical} page. Once this page is fully +assembled, the ``real'' or ``original'' |\shipout| is called to +send the physical page to the output file. + +In reality, things are slightly more complicated. First, once a +physical page has been shipped out, the logical pages are usually +voided, but this need not be the case. Instead, it is possible that +certain logical page just retain their contents after the physical +page has been shipped out and these pages need not be filled once more +before a physical shipout can occur. However, the contents of these +logical pages can still be changed using special commands. It is also +possible that after a shipout certain logical pages are filled with +the contents of \emph{other} logical pages. + +A \emph{layout} defines for each logical page where it will go on the +physical page and which further modifications should be done. The +following two commands are used to define the layout: + +\begin{command}{\pgfpagesphysicalpageoptions\marg{options}} + This command sets the characteristic of the ``physical'' page. For + example, it is used to specify how many logical pages there are and + how many logical pages must be accumulated before a physical page is + shipped out. How each individual logical page is typeset is + specified using the command |\pgfpageslogicalpageoptions|, described + later. + + \example A layout for putting two portrait pages on a single + landscape page: +\begin{codeexample}[code only] +\pgfpagesphysicalpageoptions +{% + logical pages=2,% + physical height=\paperwidth,% + physical width=\paperheight,% +} + +\pgfpageslogicalpageoptions{1} +{% + resized width=.5\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% + center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}% +}% +\pgfpageslogicalpageoptions{2} +{% + resized width=.5\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% + center=\pgfpoint{.75\pgfphysicalwidth}{.5\pgfphysicalheight}% +}% +\end{codeexample} + + The following \meta{options} may be set: + \begin{itemize} + \item \declare{|logical pages=|\meta{logical pages}} specified how many + logical pages there are, in total. These are numbered 1 to + \meta{logical pages}. + \item \declare{|first logical shipout=|\meta{first}}. See the the + next option. By default, \meta{first} is 1. + \item \declare{|last logical shipout=|\meta{last}}. Together + with the previous option, these two options define an interval of + pages inside the range 1 to \meta{logical pages}. Only this range + is used to store the pages that are shipped out by \TeX. This + means that after a physical shipout has just occured (or at the + beginning), the first time \TeX\ wishes to perform a shipout, the + page to be shipped out is stored in logical page \meta{first}. The + next time \TeX\ performs a shipout, the page is stored in logical + page $\meta{first} +1$ and so on, until the logical page + \meta{last} is also filled. Once this happens, a physical shipout + occurs and the process starts once more. + + Note that logical pages that lie outside the interval between + \meta{first} and \meta{last} are filled only indirectly or when + special commands are used. + + By default, \meta{last} equals \meta{logical pages}. + \item \declare{|current logical shipout=|\meta{current}} changes + an internal counter such that \TeX's next logical shipout will be + stored in logical page \meta{current}. + + This option can be used to ``warp'' the logical page filling + mechanism to a certain page. You can both skip logical pages and + overwrite already filled logical pages. After the logical page + \meta{current} has been filled, the internal counter is + incremented normally as if the logical page \meta{current} had + been ``reached'' normally. If you specify a \meta{current} larger + to \meta{last}, a physical shipout will occur after the logical + page \meta{current} has been filled. + \item + \declare{|physical height=|\meta{height}} + specifies the height of the physical pages. This height is + typically different from the normal |\paperheight|, which is used + by \TeX\ for its typesetting and page breaking purposes. + \item + \declare{|physical width=|\meta{width}} + specifies the physical width. + \end{itemize} +\end{command} + + +\begin{command}{\pgfpageslogicalpageoptions\marg{logical page number}\marg{options}} + This command is used to specify where the logical page number + \meta{logical page number} will be placed on the physical page. In + addition, this command can be used to install additional ``code'' to + be executed when this page is put on the physical page. + + The number \meta{logical page number} should be between 1 and + \meta{logical pages}, which has previously been installed using the + |\pgfpagesphysicalpageoptions| command. + + The following \meta{options} may be given: + \begin{itemize} + \item + \declare{|center=|\meta{pgf point}} + specifies the center of the logical page inside the physical page + as a \pgfname-point. The origin of the coordinate system of the + physical page is at the \emph{lower} left corner. + +\begin{codeexample}[code only] +\pgfpageslogicalpageoptions{1} +{% center logical page on middle of left side + center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}% + resized width=.5\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% +} +\end{codeexample} + + \item + \declare{|resized width=|\meta{size}} + specifies the width that the logical page should have \emph{at + most} on the physical page. To achieve this width, the pages is + scaled down appropriately \emph{or more}. The ``or more'' part + can happen if the |resize height| option is also used. In this + case, the scaling is chosen such that both the specified height + and width are met. The aspect ratio of a logical page is not + modified. + \item + \declare{|resized height=|\meta{height}} + specifies the maximum height of the logical page. + \item + \declare{|original width=|\meta{width}} + specifies the width the \TeX\ ``thinks'' that the logical page + has. This width is |\paperwidth| at the point of invocation, by + default. Note that setting this width to something different from + |\paperwidth| does \emph{not} change the |\pagewidth| during + \TeX's typesetting. You have to do that yourself. + + You need this option only for special logical pages that have + a height or width different from the normal one and for which you + will (later on) set these sizes yourself. + \item + \declare{|original height=|\meta{height}} + works like |original width|. + \item + \declare{|scale=|\meta{factor}} + scales the page by at least the given \meta{factor}. A + \meta{factor} of |0.5| will half the size of the page, a factor or + |2| will double the size. ``At least'' means that if options like + |resize height| are given and if the scaling required to meet that + option is less than \meta{factor}, that other scaling is used + instead. + \item + \declare{|xscale=|\meta{factor}} + scales the logical page along the $x$-axis by the given + \meta{factor}. This scaling is done independently of any other + scaling. Mostly, this option is useful for a factor of |-1|, which + flips the page along the $y$-axis. The aspect ratio is not kept. + \item + \declare{|yscale=|\meta{factor}} + works like |xscale|, only for the $y$-axis. + \item + \declare{|rotation=|\meta{degree}} + rotates the page by \meta{degree} around its center. Use a degree + of |90| or |-90| to go from portrait to landscape and back. The + rotation need not be a multiple of |90|. + \item + \declare{|copy from=|\meta{logical page number}}. + Normally, after a physical shipout has occured, all logical pages + are voided in a loop. However, if this option is given, the + current logical page is filled with the contents of the old + logical page number \meta{logical page number}. + + \example Have logical page 2 retain its contents: +\begin{codeexample}[code only] +\pgfpageslogicalpageoptions{2}{copy from=2} +\end{codeexample} + + \example Let logical page 2 show what logical page 1 showed on the + just-shipped-out physical page: +\begin{codeexample}[code only] +\pgfpageslogicalpageoptions{2}{copy from=1} +\end{codeexample} + \item + \declare{|border shrink|=\meta{size}} + specifies an addition reduction of the size to which the page is + page is scaled down. + \item + \declare{|border code|=\meta{code}}. + When this option is given, the \meta{code} is executed before the + page box is inserted with a path preinstalled that is a rectangle + around the current logical page. Thus, setting \meta{code} to + |\pgfstroke| draws a rectangle around the logical page. Setting + \meta{code} to |\pgfsetlinewidth{3pt}\pgfstroke| results in a + thick (ugly) frame. Adding dashes and filling can result in + arbitrarily funky and distracting borders. + + You can also call |\pgfdiscardpath| and add your own path + construction code (for example to paint a rectangle with rounded + corners). The coordinate system is setup in such a way that a + rectangle starting at the origin and having the height and width + of \TeX-box 0 will result in a rectangle filling exactly the + logical page currently being put on the physical page. The logical + page is inserted \emph{after} these commands have been executed. + + \example Add a rectangle around the page: +\begin{codeexample}[code only] +\pgfpageslogicalpageoptions{1}{border code=\pgfstroke} +\end{codeexample} + \item + \declare{|corner width|=\meta{size}} + adds black ``rounded corners'' to the page. See the description of + the predefined layout |rounded corners| on + page~\pageref{layout-rounded-corners}. + \end{itemize} +\end{command} + + + + +\subsection{Creating Logical Pages} + +Logical pages are created whenever a \TeX\ thinks that a page is full +and performs a |\shipout| command. This will cause |pgfpages| to store +the box that was supposed to be shipped out internally until enough +logical pages have been collected such that a physical shipout can +occur. + +Normally, whenever a logical shipout occurs that current page is +stored in logical page number \meta{current logical page}. This +counter is then incremented, until it is larger than \meta{last + logical shipout}. You can, however, directly change the value of +\meta{current logical page} by calling |\pgfpagesphysicalpageoptions|. + +Another way to set the contents of a logical page is to use the +following command: + +\begin{command}{\pgfpagesshipoutlogicalpage\marg{number}\meta{box}} + This command sets to logical page \meta{number} to \meta{box}. The + \meta{box} should be the code of a \TeX\ box command. This command + does not influence the counter \meta{current logical page} and does + not cause a physical shipout. + +\begin{codeexample}[code only] +\pgfpagesshipoutlogicalpage{0}\vbox{Hi!} +\end{codeexample} + + This command can be used to set the contents of logical pages that + are normally not filled. +\end{command} + +The final way of setting a logical page is using the following +command: + +\begin{command}{\pgfpagescurrentpagewillbelogicalpage\marg{number}} + When the current \TeX\ page has been typeset, it will be become the given + logical page \meta{number}. This command ``interrupts'' the normal + order of logical pages, that is, it behaves like the previous + command and does not update the \meta{current logical page} + counter. + +\begin{codeexample}[code only] +\pgfpagesuselayout{two screens with optional second} +... +Text for main page. +\clearpage + +\pgfpagescurrentpagewillbelogicalpage{2} +Text that goes to second page +\clearpage + +Text for main page. +\end{codeexample} +\end{command} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex new file mode 100644 index 00000000000..566464c5ea0 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex @@ -0,0 +1,275 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + +\section{Repeating Things: The Foreach Statement} +\label{section-foreach} + +In this section the package |pgffor.sty| is described. It can be used +independently of \pgfname, but it works particularly well together with +\pgfname\ and \tikzname. + +When you say |\usepackage{pgffor}|, two commands are defined: +|\foreach| and |\breakforeach|. Their behaviour is described in the +following: + +\begin{command}{\foreach| |\meta{variables}| in |\marg{list} + \meta{commands}} + The syntax of this command is a bit complicated, so let us go + through it step-by-step. + + In the easiest case, \meta{variables} is a single \TeX-command like + |\x| or |\point|. (If you want to have some fun, you can also use + active characters. If you do not know what active characters are, + you are blessed.) + + Still in the easiest case, \meta{list} is a comma-separated list of + values. Anything can be used as a value, but numbers are most + likely. + + Finally, in the easiest case, \meta{commands} is some \TeX-text in + curly braces. + + With all these assumptions, the |\foreach| statement will execute + the \meta{commands} repeatedly, once for every element of the + \meta{list}. Each time the \meta{commands} are executed, the + \meta{variable} will be set to the current value of the list item. + +\begin{codeexample}[] +\foreach \x in {1,2,3,0} {[\x]} +\end{codeexample} + + \medskip + \textbf{Syntax for the commands.} + Let use move on to a more complicated setting. The first + complication occurs when the \meta{commands} are not some text in + curly braces. If the |\foreach| statement does not encounter an + opening brace, it will instead scan everything up to the next + semicolon and use this as \meta{commands}. This is most useful in + situations like the following: + +\begin{codeexample}[] +\tikz + \foreach \x in {0,1,2,3} + \draw (\x,0) circle (0.2cm); +\end{codeexample} + + However, the ``reading till the next semicolon'' is not the whole + truth. There is another rule: If a |\foreach| statement is directly + followed by another |\foreach| statement, this second foreach + statement is collected as \meta{commands}. This allows you to write + the following: + +\begin{codeexample}[] +\begin{tikzpicture} + \foreach \x in {0,1,2,3} + \foreach \y in {0,1,2,3} + { + \draw (\x,\y) circle (0.2cm); + \fill (\x,\y) circle (0.1cm); + } +\end{tikzpicture} +\end{codeexample} + + \medskip + \textbf{The dots notation.} + The second complication concerns the \meta{list}. If this + \meta{list} contains the list item ``|...|'', this list item is replaced + by the ``missing values.'' More precisely, the following happens: + + Normally, when a list item |...| is encountered, there should + already have been \emph{two} list items before it, which where + numbers. Examples of \emph{numbers} are |1|, |-10|, or + |-0.24|. Let us call these numbers $x$ and $y$ and let $d := y-x$ be + their difference. Next, there should also be one number following + the three dots, let us call this number~$z$. + + In this situation, the part of the list reading + ``$x$|,|$y$|,...,|$z$'' is replaced by ``$x$, $x+d$, $x+2d$, $x+3d$, + \dots, $x+md$,'' where the last dots are semantic dots, not + syntactic dots. The value $m$ is the largest number such that $x + + md \le z$ if $d$ is positive or such that $x+md \ge z$ if $d$ is + negative. + + Perhaps it is best to explain this by some examples: The following + \meta{list} have the same effects: + + |\foreach \x in {1,2,...,6} {\x, }| yields \foreach \x in {1,2,...,6} {\x, } + + |\foreach \x in {1,2,3,...,6} {\x, }| yields \foreach \x in {1,2,3,...,6} {\x, } + + |\foreach \x in {1,3,...,11} {\x, }| yields \foreach \x in {1,3,...,11} {\x, } + + |\foreach \x in {1,3,...,10} {\x, }| yields \foreach \x in {1,3,...,10} {\x, } + + |\foreach \x in {0,0.1,...,0.5} {\x, }| yields \foreach \x in {0,0.1,...,0.5} {\x, } + + |\foreach \x in {a,b,9,8,...,1,2,2.125,...,2.5} {\x, }| yields \foreach \x in {a,b,9,8,...,1,2,2.125,...,2.5} {\x, } + + As can be seen, for fractional steps that are not multiples of + $2^{-n}$ for some small $n$, rounding errors can occur pretty + easily. Thus, in the second last case, |0.5| should probably be + replaced by |0.501| for robustness. + + There is yet another special case for the |...| statement: If the + |...| is used right after the first item in the list, that is, if + there is an $x$, but no $y$, the difference $d$ obviously cannot be + computed and is set to $1$ if the number $z$ following the dots is + larger than $x$ and is set to $-1$ if $z$ is smaller: + + |\foreach \x in {1,...,6} {\x, }| yields \foreach \x in {1,...,6} {\x, } + + |\foreach \x in {9,...,3.5} {\x, }| yields \foreach \x in {9,...,3.5} {\x, } + + \medskip + \textbf{Special handling of pairs.} + Different list items are separated by commas. However, this causes a + problem when the list items contain commas themselves as pairs like + |(0,1)| do. In this case, you should put the items containing commas + in braces as in |{(0,1)}|. However, since pairs are such a natural + and useful case, they get a special treatment by the |\foreach| + statement. When a list item starts with a |(| everything up to the + next |)| is made part of the item. Thus, we can write things like + the following: + +\begin{codeexample}[] +\tikz + \foreach \position in {(0,0), (1,1), (2,0), (3,1)} + \draw \position rectangle +(.25,.5); +\end{codeexample} + + \medskip + \textbf{Using the foreach-statement inside paths.} + \tikzname\ allows you to use a |\foreach| statement inside a path + construction. In such a case, the \meta{commands} must be path + construction commands. Here are two examples: + +\begin{codeexample}[] +\tikz + \draw (0,0) + \foreach \x in {1,...,3} + { -- (\x,1) -- (\x,0) } + ; +\end{codeexample} + +\begin{codeexample}[] +\tikz \draw \foreach \p in {1,...,3} {(\p,1)--(\p,3) (1,\p)--(3,\p)}; +\end{codeexample} + + \medskip + \textbf{Multiple variables.} + You will often wish to iterate over two variables at the same + time. Since you can nest |\foreach| loops, this is normally + straight-forward. However, you sometimes wish variables to + iterate ``simultaneously.'' For example, we might be given a list of + edges that connect two coordinates and might wish to iterate over + these edges. While doing so, we would like the source and target of + the edges to be set to two different variables. + + To achieve this, you can use the following syntax: The + \meta{variables} may not only be a single \TeX-variable. Instead, it + can also be a list of variables separated by slashes (|/|). In this + case the list items can also be lists of values separated by + slashes. + + Assuming that the \meta{variables} and the list items are lists of + values, each time the \meta{commands} are executed, each of the + variables in \meta{variables} is set to one part of the list making + up the current list item. Here is an example to clarify this: + + \example |\foreach \x / \y in {1/2,a/b} {``\x\ and \y''}| yields + \foreach \x / \y in {1/2,a/b} {``\x\ and \y''}. + + If some entry in the \meta{list} does not have ``enough'' slashes, + the last entry will be repeated. Here is an example: +\begin{codeexample}[] +\begin{tikzpicture} + \foreach \x/\xtext in {0,...,3,2.72 / e} + \draw (\x,0) node{$\xtext$}; +\end{tikzpicture} +\end{codeexample} + + Here are more useful examples: +\begin{codeexample}[] +\begin{tikzpicture} + % Define some coordinates: + \tikzstyle{every node}=[draw,fill] + \path[shape=circle,fill=examplefill] + (0,0) node(a) {a} + (2,0.55) node(b) {b} + (1,1.5) node(c) {c} + (2,1.75) node(d) {d}; + + % Draw some connections: + \foreach \source/\target in {a/b, b/c, c/a, c/d} + \draw (\source) .. controls +(.75cm,0pt) and +(-.75cm,0pt)..(\target); +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + % Let's draw circles at interesting points: + \foreach \x / \y / \diameter in {0 / 0 / 2mm, 1 / 1 / 3mm, 2 / 0 / 1mm} + \draw (\x,\y) circle (\diameter); + + % Same effect + \foreach \center/\diameter in {{(0,0)/2mm}, {(1,1)/3mm}, {(2,0)/1mm}} + \draw[yshift=2.5cm] \center circle (\diameter); +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture}[cap=round,line width=3pt] + \filldraw [fill=examplefill] (0,0) circle (2cm); + + \foreach \angle / \label in + {0/3, 30/2, 60/1, 90/12, 120/11, 150/10, 180/9, + 210/8, 240/7, 270/6, 300/5, 330/4} + { + \draw[line width=1pt] (\angle:1.8cm) -- (\angle:2cm); + \draw (\angle:1.4cm) node{\textsf{\label}}; + } + + \foreach \angle in {0,90,180,270} + \draw[line width=2pt] (\angle:1.6cm) -- (\angle:2cm); + + \draw (0,0) -- (120:0.8cm); % hour + \draw (0,0) -- (90:1cm); % minute +\end{tikzpicture}% +\end{codeexample} + +\begin{codeexample}[] +\tikz[shading=ball] + \foreach \x / \cola in {0/red,1/green,2/blue,3/yellow} + \foreach \y / \colb in {0/red,1/green,2/blue,3/yellow} + \shade[ball color=\cola!50!\colb] (\x,\y) circle (0.4cm); +\end{codeexample} +\end{command} + + +\begin{command}{\breakforeach} + If this command is given inside a |\foreach| command, no further + executions of the \meta{commands} will occur. However, the current + execution of the \meta{commands} is continued normally, so it is + probably best to use this command only at the end of a |\foreach| + command. + +\begin{codeexample}[] +\begin{tikzpicture} + \foreach \x in {1,...,4} + \foreach \y in {1,...,4} + { + \fill[red!50] (\x,\y) ellipse (3pt and 6pt); + + \ifnum \x<\y + \breakforeach + \fi + } +\end{tikzpicture} +\end{codeexample} + +\end{command} + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex new file mode 100644 index 00000000000..743e357485c --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex @@ -0,0 +1,865 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + +\section{Commands of the System Layer} + +\makeatletter + +\subsection{Beginning and Ending a Stream of System Commands} + +A ``user'' of the \pgfname\ system layer (like the basic layer or a +frontend) will interface with the system layer by calling a stream of +commands starting with |\pgfsys@|. From the system layer's point of +view, these commands form a long stream. Between calls to the system +layer, control goes back to the user. + +The driver files implement system layer commands by inserting +|\special| commands that implement the desired operation. For example, +|\pgfsys@stroke| will be mapped to |\special{pdf: S}| by the driver +file for |pdftex|. + +For many drivers, when such a stream of specials starts, it is +necessary to install an appropriate transformation and perhaps perform +some more bureaucratic tasks. For this reason, every stream will start +with a |\pgfsys@beginpicture| and will end with a corresponding ending +command. + +\begin{command}{\pgfsys@beginpicture} + Called at the beginning of a |{pgfpicture}|. This command should + ``setup things.'' + + Most drivers will need to implement this command. +\end{command} + +\begin{command}{\pgfsys@endpicture} + Called at the end of a pgfpicture. + + Most drivers will need to implement this command. +\end{command} + +\begin{command}{\pgfsys@typesetpicturebox\marg{box}} + Called \emph{after} a |{pgfpicture}| has been typeset. The picture + will have been put in box \meta{box}. This command should insert the + box into the normal text. The box \meta{box} will still be a ``raw'' + box that contains only the |\special|'s that make up the description + of the picture. The job of this command is to resize and shift + \meta{box} according to the baseline shift and the size of the + box. + + This command has a default implementation and need not be + implemented by a driver file. +\end{command} + +\begin{command}{\pgfsys@beginpurepicture} + This version of the |\pgfsys@beginpicture| picture command can be + used for pictures that are guaranteed not to contain any escaped + boxes (see below). In this case, a driver might provide a more + compact version of the command. + + This command has a default implementation and need not be + implemented by a driver file. +\end{command} + +\begin{command}{\pgfsys@endpurepicture} + Called at the end of a ``pure'' |{pgfpicture}|. + + This command has a default implementation and need not be + implemented by a driver file. +\end{command} + +Inside a stream it is sometimes necessary to ``escape'' back into +normal typesetting mode; for example to insert some normal text, but +with all of the current transformations and clippings being in +force. For this escaping, the following command is used: + +\begin{command}{\pgfsys@hbox\marg{box number}} + Called to insert a (horizontal) TeX box inside a + |{pgfpicture}|. + + Most drivers will need to (re-)implement this command. +\end{command} + +\begin{command}{\pgfsys@hboxsynced\marg{box number}} + Called to insert a (horizontal) TeX box inside a + |{pgfpicture}|, but with the current coordiante transformation + matrix synced with the canvas transformation matrix. + + This command should do the same as if you used + |\pgflowlevelsynccm| followed by |\pgfsys@hbox|. However, the default + implementation of this command will use a ``TeX-translation'' for + the translation part of the transformation matrix. This will ensure + that hyperlinks ``survive'' at least translations. On the other + hand, a driver may choose to revert to a simpler + implementation. This is done, for example, for the \textsc{svg} + implementation, where a \TeX-translation makes no sense. +\end{command} + + + +\subsection{Path Construction System Commands} + +\begin{command}{\pgfsys@moveto\marg{x}\marg{y}} + This command is used to start a path at a specific point + $(x,y)$ or to move the current point of the current path to $(x,y)$ + without drawing anything upon stroking (the current path is + ``interrupted''). + + Both \meta{x} and \meta{y} are given as \TeX\ dimensions. It is the + driver's job to transform these to the coordinate system of the + backend. Typically, this means converting the \TeX\ dimension into a + dimensionless multiple of $\frac{1}{72}\mathrm{in}$. The function + |\pgf@sys@bp| helps with this conversion. + + \example Draw a line from $(10\mathrm{pt},10\mathrm{pt})$ to the + origin of the picture. +\begin{codeexample}[code only] +\pgfsys@moveto{10pt}{10pt} +\pgfsys@lineto{0pt}{0pt} +\pgfsys@stroke +\end{codeexample} + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + +\begin{command}{\pgfsys@lineto\marg{x}\marg{y}} + Continue the current path to $(x,y)$ with + a straight line. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + +\begin{command}{\pgfsys@curveto\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}\marg{$x_3$}\marg{$y_3$}} + Continue the current path to $(x_3,y_3)$ + with a Bézier curve that has the two control points $(x_1,y_1)$ and $(x_2,y_2)$. + + \example Draw a good approximation of a quarter circle: +\begin{codeexample}[code only] +\pgfsys@moveto{10pt}{0pt} +\pgfsys@curveto{10pt}{5.55pt}{5.55pt}{10pt}{0pt}{10pt} +\pgfsys@stroke +\end{codeexample} + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + +\begin{command}{\pgfsys@rect\marg{x}\marg{y}\marg{width}\marg{height}} + Append a rectangle to the current path whose lower left corner is + at $(x,y)$ and whose width and height in + big points are given by \meta{width} and \meta{height}. + + This command can be ``mapped back'' to |\pgfsys@moveto| and + |\pgfsys@lineto| commands, but it is included since \pdf\ has a + special, quick version of this command. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + +\begin{command}{\pgfsys@closepath} + Close the current path. This results in joining the current point of + the path with the point specified by the last |\pgfsys@moveto| + operation. Typically, this is preferable over using |\pgfsys@lineto| + to the last point specified by a |\pgfsys@moveto|, since the line + starting at this point and the line ending at this point will be + smoothly joined by |\pgfsys@closepath|. + + \example Consider +\begin{codeexample}[code only] +\pgfsys@moveto{0pt}{0pt} +\pgfsys@lineto{10bp}{10bp} +\pgfsys@lineto{0bp}{10bp} +\pgfsys@closepath +\pgfsys@stroke +\end{codeexample} + and +\begin{codeexample}[code only] +\pgfsys@moveto{0bp}{0bp} +\pgfsys@lineto{10bp}{10bp} +\pgfsys@lineto{0bp}{10bp} +\pgfsys@lineto{0bp}{0bp} +\pgfsys@stroke +\end{codeexample} + + The difference between the above will be that in the second triangle + the corner at the origin will be wrong; it will just be the overlay + of two lines going in different directions, not a sharp pointed + corner. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + + + +\subsection{Canvas Transformation System Commands} + +\begin{command}{\pgfsys@transformcm\marg{a}\marg{b}\marg{c}\marg{d}\marg{e}\marg{f}} + Perform a concatenation of the canvas transformation matrix with the + matrix given by the values \meta{a} to \meta{f}, see the \pdf\ or + PostScript manual for details. The values \meta{a} to \meta{d} are + dimensionless factors, \meta{e} and \meta{f} are \TeX\ dimensions + + \example |\pgfsys@transformcm{1}{0}{0}{1}{1cm}{1cm}|. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + +\begin{command}{\pgfsys@transformshift\marg{x displacement}\marg{y displacement}} + This command will change the origin of the canvas to $(x,y)$. + + This command has a default implementation and need not be + implemented by a driver file. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@transformxyscale\marg{x scale}\marg{y scale}} + This command will scale the canvas (and everything that is drawn) + by a factor of \meta{x scale} in the $x$-direction and \meta{y + scale} in the $y$-direction. Note that this applies to + everything, including lines. So a scaled line will have a different + width and may even have a different width when going along the + $x$-axis and when going along the $y$-axis, if the scaling is + different in these directions. Usually, you do not want this. + + This command has a default implementation and need not be + implemented by a driver file. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + +\subsection{Stroking, Filling, and Clipping System Commands} + +\begin{command}{\pgfsys@stroke} + Stroke the current path (as if it were drawn with a pen). A number + of graphic state parameters influence this, which can be + set using appropriate system commands described later. + + \begin{description} + \item[Line width] + The ``thickness'' of the line. A width of 0 is the thinnest width + renderable on the device. On a high-resolution printer this may + become invisible and should be avoided. A good choice is 0.4pt, + which is the default. + + \item[Stroke color] + This special color is used for stroking. If it is not set, the + current color is used. + + \item[Cap] + The cap describes how the endings of lines are drawn. A round cap + adds a little half circle to these endings. A butt cap ends the + lines exactly at the end (or start) point without anything + added. A rectangular cap ends the lines like the butt cap, but the + lines protrude over the endpoint by the line thickness. (See also + the \pdf\ manual.) If the path has been closed, no cap + is drawn. + + \item[Join] + This describes how a bend (a join) in a path is rendered. A round + join draws bends using small arcs. A bevel join just draws the two + lines and then fills the join minimally so that it becomes + convex. A miter join extends the lines so that they form a single + sharp corner, but only up to a certain miter limit. (See the \pdf\ + manual once more.) + + \item[Dash] + The line may be dashed according to a dashing pattern. + + \item[Clipping area] + If a clipping area is established, only those parts of the path + that are inside the clipping area will be drawn. + \end{description} + + In addition to stroking a path, the path may also be used for + clipping after it has been stroked. This will happen if the + |\pgfsys@clipnext| is used prior to this command, see there for + details. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + +\begin{command}{\pgfsys@closestroke} + This command should have the same effect as first closing the path + and then stroking it. + + This command has a default implementation and need not be + implemented by a driver file. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + +\begin{command}{\pgfsys@fill} + This command fills the area surrounded by the current path. If the + path has not yet been closed, it is closed prior to filling. The + path itself is not stroked. For self-intersecting paths or paths + consisting of multiple parts, the nonzero winding number rule is + used to determine whether a point is inside or outside the + path, except if |\ifpgfsys@eorule| holds -- in which case the + even-odd rule should be used. (See the \pdf\ or PostScript manual + for details.) + + The following graphic state parameters influence the filling: + + \begin{description} + \item[Interior rule] + If |\ifpgfsys@eorule| is set, the even-odd rule is used, otherwise + the non-zero winding number rule. + + \item[Fill color] + If the fill color is not especially set, the current color is + used. + + \item[Clipping area] + If a clipping area is established, only those parts of the filling + area that are inside the clipping area will be drawn. + \end{description} + + In addition to filling the path, the path will also be used for + clipping if |\pgfsys@clipnext| is used prior to this command. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@fillstroke} + First, the path is filled, then the path is stroked. If the fill and + stroke colors are the same (or if they are not specified and the + current color is used), this yields almost the same as a + |\pgfsys@fill|. However, due to the line thickness of the stroked + path, the fill-stroked area will be slightly larger. + + In addition to stroking and filling the path, the path will also be + used for clipping if |\pgfsys@clipnext| is used prior to this command. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + +\begin{command}{\pgfsys@discardpath} + Normally, this command should ``throw away'' the current path. + However, after |\pgfsys@clipnext| has been called, the current path + should subsequently be used for clipping. See |\pgfsys@clipnext| for + details. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + +\begin{command}{\pgfsys@clipnext} + This command should be issued after a path has been constructed, but + before it has been stroked and/or filled or discarded. When the + command is used, the next stroking/filling/discarding command will + first be executed normally. Then, afterwards, the just-used path + will be used for subsequent clipping. If there has already been a + clipping region, this region is intersected with the new clipping + path (the clipping cannot get bigger). The nonzero winding number + rule is used to determine whether a point is inside or outside the + clipping area or the even-odd rule, depending on whether + |\ifpgfsys@eorule| holds. +\end{command} + + + + +\subsection{Graphic State Option System Commands} + +\begin{command}{\pgfsys@setlinewidth\marg{width}} + Sets the width of lines, when stroked, to \meta{width}, which must + be a \TeX\ dimension. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@buttcap} + Sets the cap to a butt cap. See |\pgfsys@stroke|. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@roundcap} + Sets the cap to a round cap. See |\pgfsys@stroke|. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@rectcap} + Sets the cap to a rectangular cap. See |\pgfsys@stroke|. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@miterjoin} + Sets the join to a miter join. See |\pgfsys@stroke|. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@setmiterlimit\marg{factor}} + Sets the miter limit of lines to \meta{factor}. See + the \pdf\ or PostScript for details on what the miter limit is. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@roundjoin} + Sets the join to a round join. See |\pgfsys@stroke|. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@beveljoin} + Sets the join to a bevel join. See |\pgfsys@stroke|. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@setdash\marg{pattern}\marg{phase}} + Sets the dashing patter. \meta{pattern} should be a list of \TeX\ + dimensions lengths separated by commas. \meta{phase} should be a + single dimension. + + \example |\pgfsys@setdash{3pt,3pt}{0pt}| + + The list of values in \meta{pattern} is used to determine the + lengths of the ``on'' phases of the dashing and of the ``off'' + phases. For example, if \meta{pattern} is |3bp,4bp|, then the dashing + pattern is ``3bp on followed by 4bp off, followed by 3bp on, + followed by 4bp off, and so on.'' A pattern of |.5pt,4pt,3pt,1.5pt| means + ``.5pt on, 4pt off, 3pt on, 1.5pt off, .5pt on, \dots'' If the + number of entries is odd, the last one is used twice, so |3pt| means + ``3pt on, 3pt off, 3pt on, 3pt off, \dots'' An empty list + means ``always on.'' + + The second argument determines the ``phase'' of the pattern. For + example, for a pattern of |3bp,4bp| and a phase of |1bp|, the pattern + would start: ``2bp on, 4bp off, 3bp on, 4bp off, 3bp on, 4bp off, + \dots'' + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +{\let\ifpgfsys@eorule=\relax +\begin{command}{\ifpgfsys@eorule} + Determines whether the even odd rule is used for filling and + clipping or not. +\end{command} +} + +\begin{command}{\pgfsys@stroke@opacity\marg{value}} + Sets the opacity of stroking operations. +\end{command} + +\begin{command}{\pgfsys@fill@opacity\marg{value}} + Sets the opacity of filling operations. +\end{command} + + +\subsection{Color System Commands} + +The \pgfname\ system layer provides a number of system commands for +setting colors. These command coexist with commands from the |color| +and |xcolor| package, which perform similar functions. However, the +|color| package does not support having two different colors for +stroking and filling, which is a useful feature that is supported by +\pgfname. For this reason, the \pgfname\ system layer offers commands for +setting these colors separatedly. Also, plain \TeX\ profits from the +fact that \pgfname\ can set colors. + +For \pdf, implementing these color commands is easy since \pdf\ +supports different stroking and filling colors directly. For +PostScript, a more complicated approach is needed in which the colors +need to be stored in special PostScript variables that are set +whenever a stroking or a filling operation is done. + +\begin{command}{\pgfsys@color@rgb\marg{red}\marg{green}\marg{blue}} + Sets the color used for stroking and filling operations to the given + red/green/blue tuple (numbers between 0 and 1). + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@rgb@stroke\marg{red}\marg{green}\marg{blue}} + Sets the color used for stroking operations to the given + red/green/blue tuple (numbers between 0 and 1). + + \example Make stroked text dark red: |\pgfsys@color@rgb@stroke{0.5}{0}{0}| + + The special stroking color is only used if the stroking color has + been set since the last |\color| or |\pgfsys@color@xxx| + command. Thus, each |\color| command will reset both the stroking + and filling colors by calling |\pgfsys@color@reset|. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@rgb@fill\marg{red}\marg{green}\marg{blue}} + Sets the color used for filling operations to the given + red/green/blue tuple (numbers between 0 and 1). This color may be + different from the stroking color. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmyk\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}} + Sets the color used for stroking and filling operations to the given + cymk tuple (numbers between 0 and 1). + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmyk@stroke\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}} + Sets the color used for stroking operations to the given cymk tuple + (numbers between 0 and 1). + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmyk@fill\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}} + Sets the color used for filling operations to the given cymk tuple + (numbers between 0 and 1). + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmy\marg{cyan}\marg{magenta}\marg{yellow}} + Sets the color used for stroking and filling operations to the given + cym tuple (numbers between 0 and 1). + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmy@stroke\marg{cyan}\marg{magenta}\marg{yellow}} + Sets the color used for stroking operations to the given cym tuple + (numbers between 0 and 1). + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmy@fill\marg{cyan}\marg{magenta}\marg{yellow}} + Sets the color used for filling operations to the given cym tuple + (numbers between 0 and 1). + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@gray\marg{black}} + Sets the color used for stroking and filling operations to the given + black value, where 0 means black and 1 means white. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@gray@stroke\marg{black}} + Sets the color used for stroking operations to the given black value, + where 0 means black and 1 means white. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@gray@fill\marg{black}} + Sets the color used for filling operations to the given black value, + where 0 means black and 1 means white. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@reset} + This command will be called when the |\color| command is used. It + should purge any internal settings of stroking and filling + color. After this call, till the next use of a command like + |\pgfsys@color@rgb@fill|, the current color installed by the + |\color| command should be used. + + If the \TeX-if |\pgfsys@color@reset@inorder| is set to true, this + command may ``assume'' that any call to a color command that sets + the fill or stroke color came ``before'' the call to this command + and may try to optimize the output accordingly. + + An example of an incorrect ``out of order'' call would be using + |\pgfsys@color@reset| at the beginning of a box that is constructed + using |\setbox|. Then, when the box is constructed, no special fill + or stroke color might be in force. However, when the box is later on + inserted at some point, a special fill color might already have been + set. In this case, this command is not guaranteed to reset the color + correctly. +\end{command} + +\begin{command}{\pgfsys@color@reset@inordertrue} + Sets the optimized ``in order'' version of the color resetting. This + is the default. +\end{command} + +\begin{command}{\pgfsys@color@reset@inorderfalse} + Switches off the optimized color resetting. +\end{command} + +\begin{command}{\pgfsys@color@unstacked\marg{\LaTeX\ color}} + This slightly obscure command causes the color stack to be + tricked. When called, this command should set the current color to + \meta{\LaTeX\ color} without causing any change in the color stack. + + \example |\pgfsys@color@unstacked{red}| +\end{command} + + +\subsection{Scoping System Commands} + +The scoping commands are used to keep changes of the graphics state +local. + +\begin{command}{\pgfsys@beginscope} + Saves the current graphic state on a graphic state stack. All + changes to the graphic state parameters mentioned for |\pgfsys@stroke| + and |\pgfsys@fill| will be local to the current graphic state and + the old values will be restored after |\pgfsys@endscope| is used. + + \emph{Warning:} \pdf\ and PostScript differ with respect to the + question of whether the current path is part of the graphic state or + not. For this reason, you should never use this command unless the + path is currently empty. For example, it might be a good idea to use + |\pgfsys@discardpath| prior to calling this command. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@endscope} + Restores the last saved graphic state. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + + + + + + +\subsection{Image System Commands} + +The system layer provides some commands for image inclusion. + +\begin{command}{\pgfsys@imagesuffixlist} + This macro should expand to a list of suffixes, separated by `:', + that will be tried when searching for an image. + + \example |\def\pgfsys@imagesuffixlist{eps:epsi:ps}| +\end{command} + + +\begin{command}{\pgfsys@defineimage} + Called, when an image should be defined. + + This command does not take any parameters. Instead, certain macros + will be preinstalled with appropriate values when this command is + invoked. These are: + + \begin{itemize} + \item\declare{|\pgf@filename|} + File name of the image to be defined. + + \item\declare{|\pgf@imagewidth|} + Will be set to the desired (scaled) width of the image. + + \item\declare{|\pgf@imageheight|} + Will be set to the desired (scaled) height of the image. + + If this macro and also the height macro are empty, the image + should have its ``natural'' size. + + If exactly only of them is specified, the undefined value the + image is scaled so that the aspect ratio is kept. + + If both are set, the image is scaled in both directions + independently, possibly changing the aspect ratio. + \end{itemize} + + The following macros presumable mostly make sense for drivers that + can handle \pdf: + + \begin{itemize} + \item \declare{|\pgf@imagepage|} + The desired page number to be extracted from a multi-page + ``image.'' + + \item\declare{|\pgf@imagemask|} + If set, it will be set to |/SMask x 0 R| where |x| is the \pdf\ + object number of a soft mask to be applied to the image. + + \item\declare{|\pgf@imageinterpolate|} + If set, it will be set to |/Interpolate true| or + |/Interpolate false|, indicating whether the image should be + interpolated in \pdf. + \end{itemize} + + The command should now setup the macro |\pgf@image| such that calling + this macro will result in typesetting the image. Thus, |\pgf@image| is + the ``return value'' of the command. + + This command has a default implementation and need not be + implemented by a driver file. +\end{command} + + +\begin{command}{\pgfsys@definemask} + This command declares a mask for usage with images. It works similar + to |\pgfsys@defineimage|: Certain macros are set when the command is + called. The result should be to set the macro |\pgf@mask| to a pdf + object count that can subsequently be used as a soft mask. The + following macros will be set when this command is invoked: + + \begin{itemize} + \item \declare{|\pgf@filename|} + File name of the mask to be defined. + + \item \declare{|\pgf@maskmatte|} + The so-called matte of the mask (see the \pdf\ documentation for + details). The matte is a color specification consisting of 1, 3 or + 4 numbers between 0 and 1. The number of numbers depends on the + number of color channels in the image (not in the mask!). It will + be assumed that the image has been preblended with this color. + \end{itemize} +\end{command} + + +\subsection{Shading System Commands} + + +\begin{command}{\pgfsys@horishading\marg{name}\marg{height}\marg{specification}} + Declares a horizontal shading for later use. The effect of this + command should be the definition of a macro called |\@pgfshading|\meta{name}|!| + (or |\csname @pdfshading|\meta{name}|!\endcsname|, to be + precise). When invoked, this new macro should insert a shading at + the current position. + + \meta{name} is the name of the shading, which is also used in the + output macro name. \meta{height} is the height of the shading and + must be given as a TeX dimension like |2cm| or + |10pt|. \meta{specification} is a shading color + specification as specified in Section~\ref{section-shadings}. The + shading specification implicitly fixes the width of the shading. + + When |\@pgfshading|\meta{name}|!| is invoked, it should insert a box + of height \meta{height} and the width implicit in the shading + declaration. +\end{command} + + +\begin{command}{\pgfsys@vertshading\marg{name}\marg{width}\marg{specification}} + Like the horizontal version, only for vertical shadings. This time, + the height of the shading is implicit in \meta{specification} and + the width is given as \meta{width}. +\end{command} + +\begin{command}{\pgfsys@radialshading\marg{name}\marg{starting point}\marg{specification}} + Declares a radial shading. Like the previous macros, this command + should setup the macro |\@pgfshading|\meta{name}|!|, which upon + invocation should insert a radial shading whose size is implicit in + \meta{specification}. + + The parameter \meta{starting point} is a \pgfname\ point + specifying the inner starting point of the shading. +\end{command} + + +\subsection{Reusable Objects System Commands} + +\begin{command}{\pgfsys@invoke\marg{literals}} + This command gets protocoled literals and should insert them into + the |.pdf| or |.dvi| file using an appropriate |\special|. +\end{command} + +\begin{command}{\pgfsys@defobject\marg{name}\marg{lower + left}\marg{upper right}\marg{code}} + Declares an object for later use. The idea is that the object can be + precached in some way and then be rendered more quickly when used + several times. For example, an arrow head might be defined and + prerendered in this way. + + The parameter \meta{name} is the name for later use. \meta{lower + left} and \meta{upper right} are \pgfname\ points specifying a bounding + box for the object. \meta{code} is the code for the object. The code + should not be too fancy. + + This command has a default implementation and need not be + implemented by a driver file. +\end{command} + +\begin{command}{\pgfsys@useobject\marg{name}\marg{extra code}} + Renders a previously declared object. The first parameter is the + name of the the object. The second parameter is extra code that + should be executed right \emph{before} the object is + rendered. Typically, this will be some transformation code. + + This command has a default implementation and need not be + implemented by a driver file. +\end{command} + + +\subsection{Invisibility System Commands} + +All drawing or stroking or text rendering between calls of the +following commands should be suppressed. A similar effect can be +achieved by clipping against an empty region, but the following +commands do not open a graphics scope and can be opened and closed +``orthogonally'' to other scopes. + +\begin{command}{\pgfsys@begininvisible} + Between this command and the closing |\pgfsys@endinvisible| all + output should be suppressed. Nothing should be drawn at all, which + includes all paths, images and shadings. However, no groups (neither + \TeX\ groups nor graphic state groups) should be opened by this + command. + + This command has a default implementation and need not be + implemented by a driver file. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@endinvisible} + Ends the invisibility section, unless invisibility blocks have been + nested. In this case, only the ``last'' one restores visibility. + + This command has a default implementation and need not be + implemented by a driver file. + + This command is protocoled, see Section~\ref{section-protocols}. +\end{command} + + + + +\subsection{Internal Conversion Commands} + +The system commands take \TeX\ dimensions as input, but the dimensions +that have to be inserted into \pdf\ and PostScript files need to be +dimensionless values that are interpreted as multiples of +$\frac{1}{72}\mathrm{in}$. For example, the \TeX\ dimension $2bp$ +should be inserted as |2| into a \pdf\ file and the \TeX\ dimension +$10\mathrm{pt}$ as |9.9626401|. To make this conversion easier, the following +command may be useful: + +\begin{command}{\pgf@sys@bp\marg{dimension}} + Inserts how many multiples of $\frac{1}{72}\mathrm{in}$ the + \meta{dimension} is into the current protocol stream (buffered). + + \example |\pgf@sys@bp{\pgf@x}| or |\pgf@sys@bp{1cm}|. +\end{command} + +Note that this command is \emph{not} a system command that can/needs +to be overwritten by a driver. + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-overview.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-overview.tex new file mode 100644 index 00000000000..091afdc9e80 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-overview.tex @@ -0,0 +1,79 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + +\section{Design of the System Layer} + +\makeatletter + + +\subsection{Driver Files} +\label{section-pgfsys} + +The \pgfname\ system layer mainly consists of a large number of +commands starting with |\pgfsys@|. These commands will be called +\emph{system commands} in the following. The higher layers +``interface'' with the system layer by calling these commands. The +higher layers should never use |\special| commands directly or even +check whether |\pdfoutput| is defined. Instead, all drawing requests +should be ``channeled'' through the system commands. + +The system layer is loaded and setup by the following package: + +\begin{package}{pgfsys} + This file provides ``default implementations'' of all system + commands, but most simply produce a warning that they are not + implemented. The actual implementations of the system commands for a + particular driver like, say, |pdftex| reside in files called + |pgfsys-xxxx.sty|, where |xxxx| is the driver name. These will be + called \emph{driver files} in the following. + + When |pgfsys.sty| is loaded, it will try to determine which driver + is used by loading |pgf.cfg|. This file should setup the macro + |\pgfsysdriver| appropriately. The, |pgfsys.sty| will input the + appropriate |pgfsys-|\meta{drivername}|.sty|. +\end{package} + +\begin{command}{\pgfsysdriver} + This macro should expand to the name of the driver to be used by + |pgfsys|. The default from |pgf.cfg| is |pgfsys-\Gin@driver|. This + is very likely to be correct if you are using \LaTeX. For plain + \TeX, the macro will be set to |pgfsys-pdftex.def| if |pdftex| is + used and to |pgfsys-dvips.def| otherwise. +\end{command} + +\begin{filedescription}{pgf.cfg} + This file should setup the command |\pgfsysdriver| correctly. If + |\pgfsysdriver| is already set to some value, the driver normally + should not change it. Otherwise, it should make a ``good guess'' at + which driver will be appropriate. +\end{filedescription} + + +The currently supported backend drivers are discussed in +Section~\ref{section-drivers}. + + +\subsection{Common Definition Files} + +Some drivers share many |\pgfsys@| commands. For the reason, files +defining these ``common'' commands are available. These files are +\emph{not} usable alone. + +\begin{filedescription}{pgfsys-common-postscript} + This file defines some |\pgfsys@| commands so that they produce + appropriate PostScript code. +\end{filedescription} + +\begin{filedescription}{pgfsys-common-pdf} + This file defines some |\pgfsys@| commands so that they produce + appropriate \textsc{pdf} code. +\end{filedescription} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex new file mode 100644 index 00000000000..0b87a7d108b --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex @@ -0,0 +1,235 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + +\section{The Soft Path Subsystem} + +\label{section-soft-paths} + +\makeatletter + + +This section describes a set of commands for creating \emph{soft + paths} as opposed to the commands of the previous section, which +created \emph{hard paths}. A soft path is a path that can still be +``changed'' or ``molded.'' Once you (or the \pgfname\ system) is +satisfied with a soft path, it is turned into a hard path, which can +be inserted into the resulting |.pdf| or |.ps| file. + +Note that the commands described in this section are ``high-level'' in +the sense that they are not implemented in driver files, but rather +directly by the \pgfname-system layer. For this reason, the commands for +creating soft paths do not start with |\pgfsys@|, but rather with +|\pgfsyssoftpath@|. On the other hand, as a user you will never use +these commands directly, so they are described as part of the +low-level interface. + + + +\subsection{Path Creation Process} + +When the user writes a command like |\draw (0bp,0bp) -- (10bp,0bp);| +quite a lot happens behind the scenes: +\begin{enumerate} +\item + The frontend command is translated by \tikzname\ into commands + of the basic layer. In essence, the command is translated to + something like +\begin{codeexample}[code only] +\pgfpathmoveto{\pgfpoint{0bp}{0bp}} +\pgfpathlineto{\pgfpoint{10bp}{0bp}} +\pgfusepath{stroke} +\end{codeexample} +\item + The |\pgfpathxxxx| command do \emph{not} directly call ``hard'' + commands like |\pgfsys@xxxx|. Instead, the command |\pgfpathmoveto| + invokes a special command called |\pgfsyssoftpath@moveto| and + |\pgfpathlineto| invokes |\pgfsyssoftpath@lineto|. + + The |\pgfsyssoftpath@xxxx| commands, which are described below, + construct a soft path. Each time such a command is used, special + tokens are added to the end of an internal macro that stores the + soft path currently being constructed. +\item + When the |\pgfusepath| is encountered, the soft path stored in + the internal macro is ``invoked.'' Only now does a special macro + iterate over the soft path. For each line-to or move-to + operation on this path it calls an appropriate |\pgfsys@moveto| or + |\pgfsys@lineto| in order to, finally, create the desired hard path, + namely, the string of literals in the |.pdf| or |.ps| file. +\item + After the path has been invoked, |\pgfsys@stroke| is called to + insert the literal for stroking the path. +\end{enumerate} + +Why such a complicated process? Why not have |\pgfpathlineto| directly +call |\pgfsys@lineto| and be done with it? There are two reasons: +\begin{enumerate} +\item + The \pdf\ specification requires that a path is not interrupted by + any non-path-construction commands. Thus, the following code will + result in a corrupted |.pdf|: +\begin{codeexample}[code only] +\pgfsys@moveto{0}{0} +\pgfsys@setlinewidth{1} +\pgfsys@lineto{10}{0} +\pgfsys@stroke +\end{codeexample} + Such corrupt code is \emph{tolerated} by most viewers, but not + always. It is much better to create only (reasonably) legal code. +\item + A soft path can still be changed, while a hard path is fixed. For + example, one can still change the starting and end points of a soft + path or do optimizations on it. Such transformations are not possible + on hard paths. +\end{enumerate} + + +\subsection{Starting and Ending a Soft Path} + +No special action must be taken in order to start the creation of a +soft path. Rather, each time a command like |\pgfsyssoftpath@lineto| +is called, a special token is added to the (global) current soft path +being constructed. + +However, you can access and change the current soft path. In this way, +it is possible to store a soft path, to manipulate it, or to invoke +it. + +\begin{command}{\pgfsyssoftpath@getcurrentpath\marg{macro name}} + This command will store the current soft path in \meta{macro name}. +\end{command} + +\begin{command}{\pgfsyssoftpath@setcurrentpath\marg{macro name}} + This command will set the current soft path to be the path stored in + \meta{macro name}. This macro should store a path that has + previously been extracted using the |\pgfsyssoftpath@getcurrentpath| + command and has possibly been modified subsequently. +\end{command} + +\begin{command}{\pgfsyssoftpath@invokecurrentpath} + This command will turn the current soft path in a ``hard'' path. To + do so, it iterates over the soft path and calls an appropriate + |\pgfsys@xxxx| command for each element of the path. Note that the + current soft path is \emph{not changed} by this command. Thus, in + order to start a new soft path after the old one has been invoked + and is no longer needed, you need to set the current soft path to be + empty. This may seems strange, but it is often useful to immediately + use the last soft path again. +\end{command} + +\begin{command}{\pgfsyssoftpath@flushcurrentpath} + This command will invoke the current soft path and then set it to be + empty. +\end{command} + + + +\subsection{Soft Path Creation Commands} + +\begin{command}{\pgfsyssoftpath@moveto\marg{x}\marg{y}} + This command appends a ``move-to'' segment to the current soft + path. The coordinates \meta{x} and \meta{y} are given as normal + \TeX\ dimensions. + + \example One way to draw a line: +\begin{codeexample}[code only] +\pgfsyssoftpath@moveto{0pt}{0pt} +\pgfsyssoftpath@lineto{10pt}{10pt} +\pgfsyssoftpath@flushcurrentpath +\pgfsys@stroke +\end{codeexample} +\end{command} + +\begin{command}{\pgfsyssoftpath@lineto\marg{x}\marg{y}} + Appends a ``line-to'' segment to the current soft path. +\end{command} + +\begin{command}{\pgfsyssoftpath@curveto\marg{a}\marg{b}\marg{c}\marg{d}\marg{x}\marg{y}} + Appends a ``curve-to'' segment to the current soft path with controls + $(a,b)$ and $(c,d)$. +\end{command} + +\begin{command}{\pgfsyssoftpath@rect\marg{lower left x}\marg{lower left y}\marg{width}\marg{height}} + Appends a rectangle segment to the current soft path. +\end{command} + +\begin{command}{\pgfsyssoftpath@closepath} + Appends a ``close-path'' segment to the current soft path. +\end{command} + + + + +\subsection{The Soft Path Data Structure} + +A soft path is stored in a standardized way, which makes it possible to +modify it before it becomes ``hard.'' Basically, a soft path is a long +sequence of triples. Each triple starts with a \emph{token} that +identifies what is going on. This token is followed by two dimensions in +braces. For example, the following is a soft path that means ``the +path starts at $(0\mathrm{bp}, 0\mathrm{bp})$ and then +continues in a straight line to $(10\mathrm{bp}, +0\mathrm{bp})$.'' + +\begin{codeexample}[code only] +\pgfsyssoftpath@movetotoken{0bp}{0bp}\pgfsyssoftpath@linetotoken{10bp}{0bp} +\end{codeexample} + +A curve-to is hard to express in this way since we need six numbers to +express it, not two. For this reasons, a curve-to is expressed using +three triples as follows: The command +\begin{codeexample}[code only] +\pgfsyssoftpath@curveto{1bp}{2bp}{3bp}{4bp}{5bp}{6bp} +\end{codeexample} +\noindent +results in the following three triples: +\begin{codeexample}[code only] +\pgfsyssoftpath@curvetosupportatoken{1bp}{2bp} +\pgfsyssoftpath@curvetosupportbtoken{3bp}{4bp} +\pgfsyssoftpath@curvetotoken{5bp}{6bp} +\end{codeexample} + +These three triples must always ``remain together.'' Thus, a lonely +|supportbtoken| is forbidden. + +In details, the following tokens exist: +\begin{itemize} +\item + \declare{|\pgfsyssoftpath@movetotoken|} indicates a move-to + operation. The two following numbers indicate the position to which + the current point should be moved. +\item + \declare{|\pgfsyssoftpath@linetotoken|} indicates a line-to + operation. +\item + \declare{|\pgfsyssoftpath@curvetosupportatoken|} indicates the first + control point of a curve-to operation. The triple must be followed + by a |\pgfsyssoftpath@curvetosupportbtoken|. +\item + \declare{|\pgfsyssoftpath@curvetosupportbtoken|} indicates the second + control point of a curve-to operation. The triple must be followed + by a |\pgfsyssoftpath@curvetotoken|. +\item + \declare{|\pgfsyssoftpath@curvetotoken|} indicates the target + of a curve-to operation. +\item + \declare{|\pgfsyssoftpath@rectcornertoken|} indicates the corner of + a rectangle on the soft path. The triple must be followed + by a |\pgfsyssoftpath@rectsizetoken|. +\item + \declare{|\pgfsyssoftpath@rectsizetoken|} indicates the size of + a rectangle on the soft path. +\item + \declare{|\pgfsyssoftpath@closepath|} indicates that the subpath + begun with the last move-to operation should be closed. The parameter + numbers are currently not important, but if set to anything + different from |{0pt}{0pt}|, they should be set to the coordinate of + the original move-to operation to which the path ``returns'' now. +\end{itemize} + + + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex new file mode 100644 index 00000000000..53e78421957 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex @@ -0,0 +1,87 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + +\section{The Protocol Subsystem} + +\label{section-protocols} + +\makeatletter + +This section describes commands for \emph{protocolling} literal text +created by \pgfname. The idea is that some literal text, like the string +of commands used to draw an arrow head, will be used over and over +again in a picture. It is then much more efficient to compute the +necessary literal text just once and to quickly insert it ``in a +single sweep.'' + +When protocolling is ``switched on,'' there is a ``current protocol'' +to which literal text gets appended. Once all commands that needed to +be protocoled have been issued, the protocol can be obtained and +stored using |\pgfsysprotocol@getcurrentprotocol|. At any point, the +current protocol can be changed using a corresponding setting +command. Finally, |\pgfsysprotocol@invokecurrentprotocol| is used to +insert the protocoled commands into the |.pdf| or |.dvi| file. + +Only those |\pgfsys@| commands can be protocolled that use the +command |\pgfsysprotocol@literal| interally. For example, the +definition of |\pgfsys@moveto| in |pgfsys-common-pdf.def| is +\begin{codeexample}[code only] +\def\pgfsys@moveto#1#2{\pgfsysprotocol@literal{#1 #2 m}} +\end{codeexample} +All ``normal'' system-level commands can be protocolled. However, +commands for creating or invoking shadings, images, or whole pictures +require special |\special|'s and cannot be protocolled. + +\begin{command}{\pgfsysprotocol@literalbuffered\marg{literal text}} + Adds the \meta{literal text} to the current protocol, after it has + been ``|\edef|ed.'' This command will always protocol. +\end{command} + +\begin{command}{\pgfsysprotocol@literal\marg{literal text}} + First calls |\pgfsysprotocol@literalbuffered| on \meta{literal + text}. Then, if protocolling is currently switched off, the + \meta{literal text} is passed on to |\pgfsys@invoke|. +\end{command} + +\begin{command}{\pgfsysprotocol@bufferedtrue} + Turns on protocolling. All subsequent calls of + |\pgfsysprotocol@literal| will append their argument to the current + protocol. +\end{command} + +\begin{command}{\pgfsysprotocol@bufferedfalse} + Turns off protocolling. Subsequent calls of + |\pgfsysprotocol@literal| directly insert their argument into the + current |.pdf| or |.ps|. + + Note that if the current protocol is not empty when protocolling is + switched off, the next call to |\pgfsysprotocol@literal| will first + flush the current protocol, that is, insert it into the file. +\end{command} + +\begin{command}{\pgfsysprotocol@getcurrentprotocol\marg{macro name}} + Stores the current protocol in \meta{macro name} for later use. +\end{command} + +\begin{command}{\pgfsysprotocol@setcurrentprotocol\marg{macro name}} + Sets the current protocol to \meta{macro name}. +\end{command} + +\begin{command}{\pgfsysprotocol@invokecurrentprotocol} + Inserts the text stored in the current protocol into the |.pdf| or + |.dvi| file. This does \emph{not} change the current protocol. +\end{command} + +\begin{command}{\pgfsysprotocol@flushcurrentprotocol} + First inserts the current protocol, then sets the current protocol + to the empty string. +\end{command} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex new file mode 100644 index 00000000000..4539f7be0fb --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex @@ -0,0 +1,1126 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Actions on Paths} + +Once a path has been constructed, different things can be done with +it. It can be drawn (or stroked) with a ``pen,'' it can be filled with +a color or shading, it can be used for clipping subsequent drawing, it +can be used to specify the extend of the picture---or any +combination of these actions at the same time. + +To decide what is to be done with a path, two methods can be +used. First, you can use a special-purpose command like |\draw| to +indicate that the path should be drawn. However, commands like |\draw| +and |\fill| are just abbreviations for special cases of the more +general method: Here, the |\path| command is used to specify the +path. Then, options encountered on the path indicate what should be +done with the path. + +For example, |\path (0,0) circle (1cm);| means ``This is a path +consisting of a circle around the origin. Do not do anything with it +(throw it away).'' However, if the option |draw| is encountered +anywhere on the path, the circle will be drawn. ``Anywhere'' is any +point on the path where an option can be given, which is everywhere +where a path command like |circle (1cm)| or |rectangle (1,1)| or even +just |(0,0)| would also be allowed. Thus, the following commands all +draw the same circle: +\begin{codeexample}[code only] +\path [draw] (0,0) circle (1cm); +\path (0,0) [draw] circle (1cm); +\path (0,0) circle (1cm) [draw]; +\end{codeexample} +Finally, |\draw (0,0) circle (1cm);| also draws a path, because +|\draw| is an abbreviation for |\path [draw]| and thus the command +expands to the first line of the above example. + +Similarly, |\fill| is an abbreviation for |\path[fill]| and +|\filldraw| is an abbreviation for the command +|\path[fill,draw]|. Since options accumulate, the following commands +all have the same effect: +\begin{codeexample}[code only] +\path [draw,fill] (0,0) circle (1cm); +\path [draw] [fill] (0,0) circle (1cm); +\path [fill] (0,0) circle (1cm) [draw]; +\draw [fill] (0,0) circle (1cm); +\fill (0,0) [draw] circle (1cm); +\filldraw (0,0) circle (1cm); +\end{codeexample} + +In the following subsection the different actions are explained that +can be performed on a path. The following commands are abbreviations for +certain sets of actions, but for many useful combinations there are no +abbreviations: + +\begin{command}{\draw} + Inside |{tikzpicture}| this is an abbreviation for |\path[draw]|. +\end{command} + +\begin{command}{\fill} + Inside |{tikzpicture}| this is an abbreviation for |\path[fill]|. +\end{command} + +\begin{command}{\filldraw} + Inside |{tikzpicture}| this is an abbreviation for |\path[fill,draw]|. +\end{command} + +\begin{command}{\shade} + Inside |{tikzpicture}| this is an abbreviation for |\path[shade]|. +\end{command} + +\begin{command}{\shadedraw} + Inside |{tikzpicture}| this is an abbreviation for |\path[shade,draw]|. +\end{command} + +\begin{command}{\clip} + Inside |{tikzpicture}| this is an abbreviation for |\path[clip]|. +\end{command} + +\begin{command}{\useasboundingbox} + Inside |{tikzpicture}| this is an abbreviation for |\path[use as bounding box]|. +\end{command} + +\begin{command}{\node} + Inside |{tikzpicture}| this is an abbreviation for |\path node|. Note + that, for once, |node| is not an option but a path operation. +\end{command} + +\begin{command}{\coordinate} + Inside |{tikzpicture}| this is an abbreviation for |\path coordinate|. +\end{command} + + + +\subsection{Specifying a Color} + +The most unspecific option for setting colors is the following: + +\begin{itemize} + \itemoption{color}|=|\meta{color name}% + \indexoption{color option}% + This option sets the color that is used for fill, drawing, and text + inside the current scope. Any special settings for filling colors or + drawing colors are immediately ``overruled'' by this option. + + The \meta{color name} is the name of a previously defined color. For + \LaTeX\ users, this is just a normal ``\LaTeX-color'' and the + |xcolor| extensions are allows. Here is an example: + +\begin{codeexample}[] +\tikz \fill[color=red!20] (0,0) circle (1ex); +\end{codeexample} + + It is possible to ``leave out'' the |color=| part and you can also + write: +\begin{codeexample}[] +\tikz \fill[red!20] (0,0) circle (1ex); +\end{codeexample} + What happens is that every option that \tikzname\ does not know, like + |red!20|, gets a ``second chance'' as a color name. + + For plain \TeX\ users, it is not so easy to specify colors since + plain \TeX\ has no ``standardized'' color naming + mechanism. Because of this, \pgfname\ emulates the |xcolor| package, + though the emulation is \emph{extremely basic} (more precisely, what + I could hack together in two hours or so). The emulation allows you + to do the following: + \begin{itemize} + \item Specify a new color using |\definecolor|. Only the two color + models |gray| and |rgb| are supported. + \example |\definecolor{orange}{rgb}{1,0.5,0}| + \item Use |\colorlet| to define a new color based on an old + one. Here, the |!| mechanism is supported, though only ``once'' + (use multiple |\colorlet| for more fancy colors). + \example |\colorlet{lightgray}{black!25}| + \item Use |\color|\marg{color name} to set the color in the current + \TeX\ group. |\aftergroup|-hackery is used to restore the color + after the group. + \end{itemize} +\end{itemize} + +As pointed out above, the |color=| option applies to ``everything'' +(except to shadings), which is not always what you want. Because of +this, there are several more specialized color options. For example, +the |draw=| option sets the color used for drawing, but does not +modify the color used for filling. These color options are documented +where the path action they influence is described. + + +\subsection{Drawing a Path} + +You can draw a path using the following option: +\begin{itemize} + \itemoption{draw}\opt{|=|\meta{color}} + Causes the path to be drawn. ``Drawing'' (also known as + ``stroking'') can be thought of as picking up a pen and moving it + along the path, thereby leaving ``ink'' on the canvas. + + There are numerous parameters that influence how a line is drawn, + like the thickness or the dash pattern. These options are explained + below. + + If the optional \meta{color} argument is given, drawing is done + using the given \meta{color}. This color can be different from the + current filling color, which allows you to draw and fill a path with + different colors. If no \meta{color} argument is given, the last + usage of the |color=| option is used. + + If the special color name |none| is given, this option causes + drawing to be ``switched off.'' This is useful if a style has + previously switched on drawing and you locally wish to undo this + effect. + + Although this option is normally used on paths to indicate that the + path should be drawn, it also makes sense to use the option with a + |{scope}| or |{tikzpicture}| environment. However, this will + \emph{not} cause all path to drawn. Instead, this just sets the + \meta{color} to be used for drawing paths inside the environment. + +\begin{codeexample}[] +\begin{tikzpicture} + \path[draw=red] (0,0) -- (1,1) -- (2,1) circle (10pt); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +The following subsections list the different options that influence +how a path is drawn. All of these options only have an effect if the +|draw| options is given (directly or indirectly). + +\subsubsection{Graphic Parameters: Line Width, Line Cap, and Line Join} + +\label{section-cap-joins} + +\begin{itemize} + \itemoption{line width}|=|\meta{dimension} + Specifies the line width. Note the space. Default: |0.4pt|. + +\begin{codeexample}[] + \tikz \draw[line width=5pt] (0,0) -- (1cm,1.5ex); +\end{codeexample} +\end{itemize} + +There are a number of predefined styles that provide more ``natural'' +ways of setting the line width. You can also redefine these +styles. Remember that you can leave out the |style=| when setting a +style. + +\begin{itemize} + \itemstyle{ultra thin} + Sets the line width to 0.1pt. +\begin{codeexample}[] + \tikz \draw[ultra thin] (0,0) -- (1cm,1.5ex); +\end{codeexample} + + \itemstyle{very thin} + Sets the line width to 0.2pt. +\begin{codeexample}[] + \tikz \draw[very thin] (0,0) -- (1cm,1.5ex); +\end{codeexample} + + \itemstyle{thin} + Sets the line width to 0.4pt. +\begin{codeexample}[] + \tikz \draw[thin] (0,0) -- (1cm,1.5ex); +\end{codeexample} + + \itemstyle{semithick} + Sets the line width to 0.6pt. +\begin{codeexample}[] + \tikz \draw[semithick] (0,0) -- (1cm,1.5ex); +\end{codeexample} + + \itemstyle{thick} + Sets the line width to 0.8pt. +\begin{codeexample}[] + \tikz \draw[thick] (0,0) -- (1cm,1.5ex); +\end{codeexample} + + \itemstyle{very thick} + Sets the line width to 1.2pt. +\begin{codeexample}[] + \tikz \draw[very thick] (0,0) -- (1cm,1.5ex); +\end{codeexample} + + \itemstyle{ultra thick} + Sets the line width to 1.6pt. +\begin{codeexample}[] + \tikz \draw[ultra thick] (0,0) -- (1cm,1.5ex); +\end{codeexample} +\end{itemize} + +\begin{itemize} + \itemoption{cap}|=|\meta{type} + Specifies how lines ``end.'' Permissible \meta{type} are |round|, + |rect|, and |butt| (default). They have the following effects: + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{scope}[line width=10pt] + \draw[cap=rect] (0,0 ) -- (1,0); + \draw[cap=butt] (0,.5) -- (1,.5); + \draw[cap=round] (0,1 ) -- (1,1); + \end{scope} + \draw[white,line width=1pt] + (0,0 ) -- (1,0) (0,.5) -- (1,.5) (0,1 ) -- (1,1); +\end{tikzpicture} +\end{codeexample} + + \itemoption{join}|=|\meta{type} + Specifies how lines ``join.'' Permissible \meta{type} are |round|, + |bevel|, and |miter| (default). They have the following effects: + +\begin{codeexample}[] +\begin{tikzpicture}[line width=10pt] + \draw[join=round] (0,0) -- ++(.5,1) -- ++(.5,-1); + \draw[join=bevel] (1.25,0) -- ++(.5,1) -- ++(.5,-1); + \draw[join=miter] (2.5,0) -- ++(.5,1) -- ++(.5,-1); + \useasboundingbox (0,1.5); % make bounding box bigger +\end{tikzpicture} +\end{codeexample} + + \itemoption{miter limit}|=|\meta{factor} + When you use the miter join and there is a very sharp corner (a + small angle), the miter join may protrude very far over the actual + joining point. In this case, if it were to protrude by + more than \meta{factor} times the line width, the miter join is + replaced by a bevel join. Default value is |10|. + +\begin{codeexample}[] +\begin{tikzpicture}[line width=5pt] + \draw (0,0) -- ++(5,.5) -- ++(-5,.5); + \draw[miter limit=25] (6,0) -- ++(5,.5) -- ++(-5,.5); + \useasboundingbox (14,0); % make bounding box bigger +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +\subsubsection{Graphic Parameters: Dash Pattern} + +\begin{itemize} + \itemoption{dash pattern}|=|\meta{dash pattern} + Sets the dashing pattern. The syntax is the same as in + \textsc{metafont}. For example |on 2pt off 3pt on 4pt off 4pt| means ``draw + 2pt, then leave out 3pt, then draw 4pt once more, then leave out 4pt + again, repeat''. + +\begin{codeexample}[] +\begin{tikzpicture}[dash pattern=on 2pt off 3pt on 4pt off 4pt] + \draw (0pt,0pt) -- (3.5cm,0pt); +\end{tikzpicture} +\end{codeexample} + + \itemoption{dash phase}|=|\meta{dash phase} + Shifts the start of the dash pattern by \meta{phase}. + +\begin{codeexample}[] +\begin{tikzpicture}[dash pattern=on 20pt off 10pt] + \draw[dash phase=0pt] (0pt,3pt) -- (3.5cm,3pt); + \draw[dash phase=10pt] (0pt,0pt) -- (3.5cm,0pt); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +As for the line thickness, some predefined styles allow you to set the +dashing conveniently. + +\begin{itemize} +\itemstyle{solid} + Shorthand for setting a solid line as ``dash pattern.'' This is the default. + +\begin{codeexample}[] +\tikz \draw[solid] (0pt,0pt) -- (50pt,0pt); +\end{codeexample} + + \itemstyle{dotted} + Shorthand for setting a dotted dash pattern. + +\begin{codeexample}[] +\tikz \draw[dotted] (0pt,0pt) -- (50pt,0pt); +\end{codeexample} + + \itemstyle{densely dotted} + Shorthand for setting a densely dotted dash pattern. + +\begin{codeexample}[] +\tikz \draw[densely dotted] (0pt,0pt) -- (50pt,0pt); +\end{codeexample} + + \itemstyle{loosely dotted} + Shorthand for setting a loosely dotted dash pattern. + +\begin{codeexample}[] +\tikz \draw[loosely dotted] (0pt,0pt) -- (50pt,0pt); +\end{codeexample} + + \itemstyle{dashed} + Shorthand for setting a dashed dash pattern. + +\begin{codeexample}[] +\tikz \draw[dashed] (0pt,0pt) -- (50pt,0pt); +\end{codeexample} + + \itemstyle{densely dashed} + Shorthand for setting a densely dashed dash pattern. + +\begin{codeexample}[] +\tikz \draw[densely dashed] (0pt,0pt) -- (50pt,0pt); +\end{codeexample} + + \itemstyle{loosely dashed} + Shorthand for setting a loosely dashed dash pattern. + +\begin{codeexample}[] +\tikz \draw[loosely dashed] (0pt,0pt) -- (50pt,0pt); +\end{codeexample} +\end{itemize} + + +\subsubsection{Graphic Parameters: Draw Opacity} + +When a line is drawn, it will normally ``obscure'' everything behind +it as if you has used perfectly opaque ink. It is also possible to ask +\tikzname\ to use an ink that is a little bit (or a big bit) +transparent. To do so, use the following option: + +\begin{itemize} + \itemoption{draw opacity}|=|\meta{value} + This option sets ``how transparent'' lines should be. A value of |1| + means ``fully opaque'' or ``not transparent at all,'' a value of |0| + means ``fully transparent'' or ``invisible.'' A value of |0.5| + yields lines that are semitransparent. + + Note that when you use PostScript as your output format, + this option works only with recent versions of GhostScript. + +\begin{codeexample}[] +\begin{tikzpicture}[line width=1ex] + \draw (0,0) -- (3,1); + \filldraw [fill=examplefill,draw opacity=0.5] (1,0) rectangle (2,1); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +Note that the |draw opacity| options only sets the opacity of drawn +lines. The opacity of fillings is set using the option +|fill opacity| (documented in Section~\ref{section-fill-opacity}. The +option |opacity| sets both at the same time. + +\begin{itemize} + \itemoption{opacity}|=|\meta{value} + Sets both the drawing and filling opacity to \meta{value}. + + The following predefined styles make it easier to use this option: + \begin{itemize} + \itemstyle{transparent} + Makes everything totally transparent and, hence, invisible. + +\begin{codeexample}[] +\tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[transparent,red] (0.5,0) rectangle (1.5,0.25); } +\end{codeexample} + \itemstyle{ultra nearly transparent} + Makes everything, well, ultra nearly transparent. + +\begin{codeexample}[] +\tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[ultra nearly transparent] (0.5,0) rectangle (1.5,0.25); } +\end{codeexample} + \itemstyle{very nearly transparent} +\begin{codeexample}[] +\tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[very nearly transparent] (0.5,0) rectangle (1.5,0.25); } +\end{codeexample} + \itemstyle{nearly transparent} +\begin{codeexample}[] +\tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[nearly transparent] (0.5,0) rectangle (1.5,0.25); } +\end{codeexample} + \itemstyle{semitransparent} +\begin{codeexample}[] +\tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[semitransparent] (0.5,0) rectangle (1.5,0.25); } +\end{codeexample} + \itemstyle{nearly opaque} +\begin{codeexample}[] +\tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[nearly opaque] (0.5,0) rectangle (1.5,0.25); } +\end{codeexample} + \itemstyle{very nearly opaque} +\begin{codeexample}[] +\tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[very nearly opaque] (0.5,0) rectangle (1.5,0.25); } +\end{codeexample} + \itemstyle{ultra nearly opaque} +\begin{codeexample}[] +\tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[ultra nearly opaque] (0.5,0) rectangle (1.5,0.25); } +\end{codeexample} + \itemstyle{opaque} + This yields completely opaque drawings, which is the default. +\begin{codeexample}[] +\tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[opaque] (0.5,0) rectangle (1.5,0.25); } +\end{codeexample} + \end{itemize} +\end{itemize} + + + + +\subsubsection{Graphic Parameters: Arrow Tips} + +When you draw a line, you can add arrow tips at the ends. It is +only possible to add one arrow tip at the start and one at the end. If +the path consists of several segments, only the last segment gets +arrow tips. The behavior for paths that are closed is not specified +and may change in the future. + +\begin{itemize} +\itemoption{arrows}\opt{|=|\meta{start arrow kind}|-|\meta{end arrow kind}} + This option sets the start and end arrow tips (an empty value as in |->| + indicates that no arrow tip should be drawn at the start).% + \indexoption{arrows} + + \emph{Note: Since the arrow option is so often used, you can leave + out the text |arrows=|.} What happens is that every option that + contains a |-| is interpreted as an arrow specification. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[->] (0,0) -- (1,0); + \draw[o-stealth] (0,0.3) -- (1,0.3); +\end{tikzpicture} +\end{codeexample} + + The permissible values are all predefined arrow tips, though + you can also define new arrow tip kinds as explained in + Section~\ref{section-arrows}. This is often necessary to obtain + ``double'' arrow tips and arrow tips that have a fixed size. Since + |pgflibraryarrows| is loaded by default, all arrow tips described in + Section~\ref{section-library-arrows} are available. + + One arrow tip kind is special: |>| (and all arrow tip kinds containing the + arrow tip kind such as |<<| or \verb!>|!). This arrow tip type is not + fixed. Rather, you can redefine it using the |>=| option, see + below. + + \example You can also combine arrow tip types as in +\begin{codeexample}[] +\begin{tikzpicture}[thick] + \draw[to reversed-to] (0,0) .. controls +(.5,0) and +(-.5,-.5) .. +(1.5,1); + \draw[[-latex reversed] (1,0) .. controls +(.5,0) and +(-.5,-.5) .. +(1.5,1); + \draw[latex-)] (2,0) .. controls +(.5,0) and +(-.5,-.5) .. +(1.5,1); + \useasboundingbox (-.1,-.1) rectangle (3.1,1.1); % make bounding box bigger +\end{tikzpicture} +\end{codeexample} + + \itemoption{>}|=|\meta{end arrow kind} + This option can be used to redefine the ``standard'' arrow tip |>|. The + idea is that different people have different ideas what arrow tip kind + should normally be used. I prefer the arrow tip of \TeX's |\to| command + (which is used in things like $f\colon A \to B$). Other people will + prefer \LaTeX's standard arrow tip, which looks like this: \tikz + \draw[-latex] (0,0) -- (10pt,1ex);. Since the arrow tip kind |>| is + certainly the most ``natural'' one to use, it is kept free of any + predefined meaning. Instead, you can change it by saying |>=to| to + set the ``standard'' arrow tip kind to \TeX's arrow tip, whereas |>=latex| + will set it to \LaTeX's arrow tip and |>=stealth| will use a + \textsc{pstricks}-like arrow tip. + + Apart from redefining the arrow tip kind |>| (and |<| for the start), + this option also redefines the following arrow tip kinds: |>| and |<| as + the swapped version of \meta{end arrow kind}, |<<| and |>>| as + doubled versions, |>>| and |<<| as swapped doubled versions, %>> + and \verb!|<! and \verb!>|! as arrow tips ending with a vertical bar. + +\begin{codeexample}[] +\begin{tikzpicture}[scale=2] + \begin{scope}[>=latex] + \draw[->] (0pt,6ex) -- (1cm,6ex); + \draw[>->>] (0pt,5ex) -- (1cm,5ex); + \draw[|<->|] (0pt,4ex) -- (1cm,4ex); + \end{scope} + \begin{scope}[>=diamond] + \draw[->] (0pt,2ex) -- (1cm,2ex); + \draw[>->>] (0pt,1ex) -- (1cm,1ex); + \draw[|<->|] (0pt,0ex) -- (1cm,0ex); + \end{scope} +\end{tikzpicture} +\end{codeexample} + + \itemoption{shorten >}|=|\meta{dimension} + This option will shorten the end of lines by the given + \meta{dimension}. If you specify an arrow tip, lines are already + shortened a bit such that the arrow tip touches the specified endpoint + and does not ``protrude over'' this point. Here is an example: + +\begin{codeexample}[] +\begin{tikzpicture}[line width=20pt] + \useasboundingbox (0,-1.5) rectangle (3.5,1.5); + \draw[red] (0,0) -- (3,0); + \draw[gray,->] (0,0) -- (3,0); +\end{tikzpicture} +\end{codeexample} + + The |shorten >| option allows you to shorten the end on the line + \emph{additionally} by the given distance. This option can also be + useful if you have not specified an arrow tip at all. + +\begin{codeexample}[] +\begin{tikzpicture}[line width=20pt] + \useasboundingbox (0,-1.5) rectangle (3.5,1.5); + \draw[red] (0,0) -- (3,0); + \draw[-to,shorten >=10pt,gray] (0,0) -- (3,0); +\end{tikzpicture} +\end{codeexample} + + \itemoption{shorten <}|=|\meta{dimension} works like |shorten >|, + but for the start. +\end{itemize} + + + +\subsubsection{Graphic Parameters: Double Lines and Bordered Lines} + +\begin{itemize} + \itemoption{double}\opt{|=|\meta{core color}} + This option causes ``two'' lines to be drawn instead of a single + one. However, this is not what really happens. In reality, the path + is drawn twice. First, with the normal drawing color, secondly with + the \meta{core color}, which is normally |white|. Upon the second + drawing, the line width is reduced. The net effect is that it + appears as if two lines had been drawn and this works well even with + complicated, curved paths: + +\begin{codeexample}[] +\tikz \draw[double] + plot[smooth cycle] coordinates{(0,0) (1,1) (1,0) (0,1)}; +\end{codeexample} + + You can also use the doubling option to create an effect in which a + line seems to have a certain ``border'': + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) -- (1,1); + \draw[draw=white,double=red,very thick] (0,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + \itemoption{double distance}|=|\meta{dimension} + Sets the distance the ``two'' lines are spaced apart (default is + 0.6pt). In reality, this is the thickness of the line that is used + to draw the path for the second time. The thickness of the + \emph{first} time the path is drawn is twice the normal line width + plus the given \meta{dimension}. As a side-effect, this option + ``selects'' the |double| option. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[very thick,double] (0,0) arc (180:90:1cm); + \draw[very thick,double distance=2pt] (1,0) arc (180:90:1cm); + \draw[thin,double distance=2pt] (2,0) arc (180:90:1cm); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + + + + + + + +\subsection{Filling a Path} +\label{section-rules} +To fill a path, use the following option: +\begin{itemize} + \itemoption{fill}\opt{|=|\meta{color}} + This option causes the path to be filled. All unclosed parts of the + path are first closed, if necessary. Then, the area enclosed by the + path is filled with the current filling color, which is either the + last color set using the general |color=| option or the optional + color \meta{color}. For self-intersection paths and for paths + consisting of several closed areas, the ``enclosed area'' is + somewhat complicated to define and two different definitions exist, + namely the nonzero winding number rule and the even odd rule, see + the explanation of these options, below. + + Just as for the |draw| option, setting \meta{color} to |none| + disables filling locally. + +\begin{codeexample}[] +\begin{tikzpicture} + \fill (0,0) -- (1,1) -- (2,1); + \fill (4,0) circle (.5cm) (4.5,0) circle (.5cm); + \fill[even odd rule] (6,0) circle (.5cm) (6.5,0) circle (.5cm); + \fill (8,0) -- (9,1) -- (10,0) circle (.5cm); +\end{tikzpicture} +\end{codeexample} + + If the |fill| option is used together with the |draw| option (either + because both are given as options or because a |\filldraw| command + is used), the path is filled \emph{first}, then the path is drawn + \emph{second}. This is especially useful if different colors are + selected for drawing and for filling. Even if the same color is + used, there is a difference between this command and a plain + |fill|: A ``filldrawn'' area will be slightly larger than a filled + area because of the thickness of the ``pen.'' + +\begin{codeexample}[] +\begin{tikzpicture}[fill=examplefill,line width=5pt] + \filldraw (0,0) -- (1,1) -- (2,1); + \filldraw (4,0) circle (.5cm) (4.5,0) circle (.5cm); + \filldraw[even odd rule] (6,0) circle (.5cm) (6.5,0) circle (.5cm); + \filldraw (8,0) -- (9,1) -- (10,0) circle (.5cm); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + + +\subsubsection{Graphic Parameters: Interior Rules} + +The following two options can be used to decide how interior points +should be determined: +\begin{itemize} + \itemoption{nonzero rule} + If this rule is used (which is the default), the following method is + used to determine whether a given point is ``inside'' the path: From + the point, shoot a ray in some direction towards infinity (the + direction is chosen such that no strange borderline cases + occur). Then the ray may hit the path. Whenever it hits the path, we + increase or decrease a counter, which is initially zero. If the ray + hits the path as the path goes ``from left to right'' (relative to + the ray), the counter is increased, otherwise it is decreased. Then, + at the end, we check whether the counter is nonzero (hence the + name). If so, the point is deemed to lie ``inside,'' otherwise it is + ``outside.'' Sounds complicated? It is. + +\begin{codeexample}[] +\begin{tikzpicture} + \filldraw[fill=examplefill] + % Clockwise rectangle + (0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle + % Counter-clockwise rectangle + (0.25,0.25) -- (0.75,0.25) -- (0.75,0.75) -- (0.25,0.75) -- cycle; + + \draw[->] (0,1) (.4,1); + \draw[->] (0.75,0.75) (0.3,.75); + + \draw[->] (0.5,0.5) -- +(0,1) node[above] {crossings: $-1+1 = 0$}; + + \begin{scope}[yshift=-3cm] + \filldraw[fill=examplefill] + % Clockwise rectangle + (0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle + % Clockwise rectangle + (0.25,0.25) -- (0.25,0.75) -- (0.75,0.75) -- (0.75,0.25) -- cycle; + + \draw[->] (0,1) (.4,1); + \draw[->] (0.25,0.75) (0.4,.75); + + \draw[->] (0.5,0.5) -- +(0,1) node[above] {crossings: $1+1 = 2$}; + \end{scope} +\end{tikzpicture} +\end{codeexample} + +\itemoption{even odd rule} + This option causes a different method to be used for determining the + inside and outside of paths. While it is less flexible, it turns out + to be more intuitive. + + With this method, we also shoot rays from the point for which we + wish to determine whether it is inside or outside the filling + area. However, this time we only count how often we ``hit'' the path + and declare the point to be ``inside'' if the number of hits is odd. + + Using the even-odd rule, it is easy to ``drill holes'' into a path. + +\begin{codeexample}[] +\begin{tikzpicture} + \filldraw[fill=examplefill,even odd rule] + (0,0) rectangle (1,1) (0.5,0.5) circle (0.4cm); + \draw[->] (0.5,0.5) -- +(0,1) [above] node{crossings: $1+1 = 2$}; +\end{tikzpicture} +\end{codeexample} +\end{itemize} + + + +\subsubsection{Graphic Parameters: Fill Opacity} + +\label{section-fill-opacity} +Analogously to the |draw opacity|, you can also set the filling +opacity: + +\begin{itemize} + \itemoption{fill opacity}|=|\meta{value} + This option sets the opacity of fillings. In addition to filling + operations, this opacity also applies to text and images. + + Note, again, that when you use PostScript as your output format, + this option works only with recent versions of GhostScript. + +\begin{codeexample}[] +\begin{tikzpicture}[thick,fill opacity=0.5] + \filldraw[fill=red] (0:1cm) circle (12mm); + \filldraw[fill=green] (120:1cm) circle (12mm); + \filldraw[fill=blue] (-120:1cm) circle (12mm); +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \fill[red] (0,0) rectangle (3,2); + + \node at (0,0) {\huge A}; + \node[fill opacity=0.5] at (3,2) {\huge B}; +\end{tikzpicture} +\end{codeexample} +\end{itemize} + + +\subsection{Shading a Path} + +You can shade a path using the |shade| option. A shading is like a +filling, only the shading changes its color smoothly from one color to +another. + +\begin{itemize} + \itemoption{shade} + Causes the path to be shaded using the currently selected shading + (more on this later). If this option is used together with the + |draw| option, then the path is first shaded, then drawn. + + It is not an error to use this option together with the |fill| + option, but it makes no sense. + +\begin{codeexample}[] +\tikz \shade (0,0) circle (1ex); +\end{codeexample} + +\begin{codeexample}[] +\tikz \shadedraw (0,0) circle (1ex); +\end{codeexample} +\end{itemize} + +For some shadings it is not really clear how they can ``fill'' the +path. For example, the |ball| shading normally looks like this: \tikz +\shade[shading=ball] (0,0) circle (0.75ex);. How is this supposed to +shade a rectangle? Or a triangle? + +To solve this problem, the predefined shadings like |ball| or |axis| +fill a large rectangle completely in a sensible way. Then, when the +shading is used to ``shade'' a path, what actually happens is that the +path is temporarily used for clipping and then the rectangular shading +is drawn, scaled and shifted such that all parts of the path are +filled. + + +\subsubsection{Choosing a Shading Type} + +The default shading is a smooth transition from gray +to white and from above to bottom. However, other shadings are also +possible, for example a shading that will sweep a color from the +center to the corners outward. To choose the shading, you can use the +|shading=| option, which will also automatically invoke the |shade| +option. Note that this does \emph{not} change the shading color, only +the way the colors sweep. For changing the colors, other options are +needed, which are explained below. + +\begin{itemize} + \itemoption{shading}|=|\meta{name} + This selects a shading named \meta{name}. The following shadings are + predefined: + \begin{itemize} + \item \declare{|axis|} + This is the default shading in which the color changes gradually + between three horizontal lines. The top line is at the top + (uppermost) point of the path, the middle is in the middle, the + bottom line is at the bottom of the path. + +\begin{codeexample}[] +\tikz \shadedraw [shading=axis] (0,0) rectangle (1,1); +\end{codeexample} + + The default top color is gray, the default bottom color is white, + the default middle is the ``middle'' of these two. + \item \declare{|radial|} + This shading fills the path with a gradual sweep from a certain + color in the middle to another color at the border. If the path is + a circle, the outer color will be reached exactly at the + border. If the shading is not a circle, the outer color will + continue a bit towards the corners. The default inner color is + gray, the default outer color is white. + +\begin{codeexample}[] +\tikz \shadedraw [shading=radial] (0,0) rectangle (1,1); +\end{codeexample} + \item \declare{|ball|} + This shading fills the path with a shading that ``looks like a + ball.'' The default ``color'' of the ball is blue (for no + particular reason). + +\begin{codeexample}[] +\tikz \shadedraw [shading=ball] (0,0) rectangle (1,1); +\end{codeexample} + +\begin{codeexample}[] +\tikz \shadedraw [shading=ball] (0,0) circle (.5cm); +\end{codeexample} + \end{itemize} + \itemoption{shading angle}|=|\meta{degrees} + This option rotates the shading (not the path!) by the given + angle. For example, we can turn a top-to-bottom axis shading into a + left-to-right shading by rotating it by $90^\circ$. + +\begin{codeexample}[] +\tikz \shadedraw [shading=axis,shading angle=90] (0,0) rectangle (1,1); +\end{codeexample} +\end{itemize} + + +You can also define new shading types yourself. However, for this, you +need to use the basic layer directly, which is, well, more basic and +harder to use. Details on how to create a shading appropriate for +filling paths are given in Section~\ref{section-shading-a-path}. + + + +\subsubsection{Choosing a Shading Color} + +The following options can be used to change the colors used for +shadings. When one of these options is given, the |shade| option is +automatically selected and also the ``right'' shading. + +\begin{itemize} + \itemoption{top color}|=|\meta{color} + This option prescribes the color to be used at the top in an |axis| + shading. When this option is given, several things happen: + \begin{enumerate} + \item + The |shade| option is selected. + \item + The |shading=axis| option is selected. + \item + The middle color of the axis shading is set to the average of the + given top color \meta{color} and of whatever color is currently + selected for the bottom. + \item + The rotation angle of the shading is set to 0. + \end{enumerate} + +\begin{codeexample}[] +\tikz \draw[top color=red] (0,0) rectangle (2,1); +\end{codeexample} + + \itemoption{bottom color}|=|\meta{color} + This option works like |top color|, only for the bottom color. + + \itemoption{middle color}|=|\meta{color} + This option specifies the color for the middle of an axis + shading. It also sets the |shade| and |shading=axis| options, but it + does not change the rotation angle. + + \emph{Note:} Since both |top color| and |bottom color| change the + middle color, this option should be given \emph{last} if all of + these options need to be given: + +\begin{codeexample}[] +\tikz \draw[top color=white,bottom color=black,middle color=red] + (0,0) rectangle (2,1); +\end{codeexample} + + \itemoption{left color}|=|\meta{color} + This option does exactly the same as |top color|, except that the + shading angle is set to $90^\circ$. + + \itemoption{right color}|=|\meta{color} + Works like |left color|. + + \itemoption{inner color}|=|\meta{color} + This option sets the color used at the center of a |radial| + shading. When this option is used, the |shade| and |shading=radial| + options are set. + +\begin{codeexample}[] +\tikz \draw[inner color=red] (0,0) rectangle (2,1); +\end{codeexample} + + \itemoption{outer color}|=|\meta{color} + This option sets the color used at the border and outside of a + |radial| shading. + +\begin{codeexample}[] +\tikz \draw[outer color=red,inner color=white] + (0,0) rectangle (2,1); +\end{codeexample} + + \itemoption{ball color}|=|\meta{color} + This option sets the color used for the ball shading. It sets the + |shade| and |shading=ball| options. Note that the ball will never + ``completely'' have the color \meta{color}. At its ``highlight'' spot + a certain amount of white is mixed in, at the border a certain + amount of black. Because of this, it also makes sense to say + |ball color=white| or |ball color=black| + +\begin{codeexample}[] +\begin{tikzpicture} + \shade[ball color=white] (0,0) circle (2ex); + \shade[ball color=red] (1,0) circle (2ex); + \shade[ball color=black] (2,0) circle (2ex); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + + + + +\subsection{Establishing a Bounding Box} + +\pgfname\ is reasonably good at keeping track of the size of your picture +and reserving just the right amount of space for it in the main +document. However, in some cases you may want to say things like +``do not count this for the picture size'' or ``the picture is +actually a little large.'' For this you can use the option +|use as bounding box| or the command |\useasboundingbox|, which is just +a shorthand for |\path[use as bounding box]|. + +\begin{itemize} + \itemoption{use as bounding box} + Normally, when this option is given on a path, the bounding box of + the present path is used to determine the size of the picture and + the size of all \emph{subsequent} paths are + ignored. However, if there were previous path operations that have + already established a larger bounding box, it will not be made + smaller by this operation. + + In a sense, |use as bounding box| has the same effect as clipping + all subsequent drawing against the current path---without actually + doing the clipping, only making \pgfname\ treat everything as if it + were clipped. + + The first application of this option is to have a |{tikzpicture}| + overlap with the main text: + +\begin{codeexample}[] +Left of picture\begin{tikzpicture} + \draw[use as bounding box] (2,0) rectangle (3,1); + \draw (1,0) -- (4,.75); +\end{tikzpicture}right of picture. +\end{codeexample} + + In a second application this option can be used to get better + control over the white space around the picture: + +\begin{codeexample}[] +Left of picture +\begin{tikzpicture} + \useasboundingbox (0,0) rectangle (3,1); + \fill (.75,.25) circle (.5cm); +\end{tikzpicture} +right of picture. +\end{codeexample} + + Note: If this option is used on a path inside a \TeX\ group (scope), + the effect ``lasts'' only till the end of the scope. Again, this + behavior is the same as for clipping. +\end{itemize} + +There is a node that allows you to get the size of the current +bounding box. The |current bounding box| node has the |rectangle| +shape |rectangle| shape and its size is always the size of the current +bounding box. + + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[red] (0,0) circle (2pt); + \draw[red] (2,1) circle (3pt); + + \draw (current bounding box.south west) rectangle + (current bounding box.north east); + + \draw[red] (3,-1) circle (4pt); + + \draw[thick] (current bounding box.south west) rectangle + (current bounding box.north east); +\end{tikzpicture} +\end{codeexample} + + + + + +\subsection{Using a Path For Clipping} + +To use a path for clipping, use the |clip| option. + +\begin{itemize} + \itemoption{clip} + This option causes all subsequent drawings to be clipped against the + current path and the size of subsequent paths will not be important + for the picture size. If you clip against a self-intersecting path, + the even-odd rule or the nonzero winding number rule is used to + determine whether a point is inside or outside the clipping region. + + The clipping path is a graphic state parameter, so it will be reset + at the end of the current scope. Multiple clippings accumulate, that + is, clipping is always done against the intersection of all clipping + areas that have been specified inside the current scopes. The only + way of enlarging the clipping area is to end a |{scope}|. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[clip] (0,0) circle (1cm); + \fill[red] (1,0) circle (1cm); +\end{tikzpicture} +\end{codeexample} + + It is usually a \emph{very} good idea to apply the |clip| option only + to the first path command in a scope. + + If you ``only wish to clip'' and do not wish to draw anything, you can + use the |\clip| command, which is a shorthand for |\path[clip]|. + +\begin{codeexample}[] +\begin{tikzpicture} + \clip (0,0) circle (1cm); + \fill[red] (1,0) circle (1cm); +\end{tikzpicture} +\end{codeexample} + + To keep clipping local, use |{scope}| environments as in the + following example: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) -- ( 0:1cm); + \draw (0,0) -- (10:1cm); + \draw (0,0) -- (20:1cm); + \draw (0,0) -- (30:1cm); + \begin{scope}[fill=red] + \fill[clip] (0.2,0.2) rectangle (0.5,0.5); + + \draw (0,0) -- (40:1cm); + \draw (0,0) -- (50:1cm); + \draw (0,0) -- (60:1cm); + \end{scope} + \draw (0,0) -- (70:1cm); + \draw (0,0) -- (80:1cm); + \draw (0,0) -- (90:1cm); +\end{tikzpicture} +\end{codeexample} + + There is a slightly annoying catch: You cannot specify certain graphic + options for the command used for clipping. For example, in the above + code we could not have moved the |fill=red| to the |\fill| + command. The reasons for this have to do with the internals of the + \pdf\ specification. You do not want to know the details. It is best + simply not to specify any options for these + commands. +\end{itemize} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex new file mode 100644 index 00000000000..6ce31747a18 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex @@ -0,0 +1,301 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Specifying Coordinates} + + +\subsection{Coordinates and Coordinate Options} + +A \emph{coordinate} is a position in a picture. \tikzname\ uses a +special syntax for specifying coordinates. Coordinates are always put +in round brackets. The general syntax is +\declare{|(|\opt{|[|\meta{options}|]|}\meta{coordinate specification}|)|}. + +It is possible to give options that apply only to a single +coordinate, although this makes sense for transformation options +only. To give transformation options for a single coordinate, give +these options at the beginning in brackets: +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1); + \draw[red] (0,0) -- ([xshift=3pt] 1,1); + \draw (1,0) -- +(30:2cm); + \draw[red] (1,0) -- +([shift=(135:5pt)] 30:2cm); +\end{tikzpicture} +\end{codeexample} + +\subsection{Simple Coordinates} + +The simplest way to specify coordinates is as a comma-separated pair +of \TeX\ dimensions as in |(1cm,2pt)| or |(2cm,\textheight)|. As can +be seen, different units can be mixed. The coordinate specified in +this way means ``1cm to the right and 2pt up from the origin of the +picture.'' You can also write things like |(1cm+2pt,2pt)| since the +|calc| package is used. + + +\subsection{Polar Coordinates} + +You can also specify coordinates in polar coordinates. In this case, +you specify an angle and a distance, separated by a colon as in +|(30:1cm)|. The angle must always be given in degrees and should be +between $-360$ and $720$. + +\begin{codeexample}[] +\tikz \draw (0cm,0cm) -- (30:1cm) -- (60:1cm) -- (90:1cm) + -- (120:1cm) -- (150:1cm) -- (180:1cm); +\end{codeexample} + +Instead of an angle given as a number you can also use certain +words. For example, |up| is the same as |90|, so that you can write +|\tikz \draw (0,0) -- (2ex,0pt) -- +(up:1ex);| +and get \tikz \draw (0,0) -- (2ex,0pt) -- +(up:1ex);. Apart from |up| +you can use |down|, |left|, |right|, |north|, |south|, |west|, |east|, +|north east|, |north west|, |south east|, |south west|, all of which +have their natural meaning. + + + +\subsection{Xy- and Xyz-Coordinates} + +You can specify coordinates in \pgfname's $xy$-coordinate system. In +this case, you provide two unit-free numbers, separated by a comma as +in |(2,-3)|. This means ``add twice the current \pgfname\ $x$-vector and +subtract three times the $y$-vector.'' By default, the $x$-vector +points 1cm to the right, the $y$-vector points 1cm upwards, but this +can be changed arbitrarily using the |x| and~|y| graphic options. + +Similarly, you can specify coordinates in the $xyz$-coordinate +system. The only difference to the $xy$-coordinates is that you +specify three numbers separated by commas as in |(1,2,3)|. This is +interpreted as ``once the $x$-vector plus twice the $y$-vector plus +three times the $z$-vector.'' The default $z$-vector points to +$\bigl(-\frac{1}{\sqrt2} +\textrm{cm},-\frac{1}{\sqrt2}\textrm{cm}\bigr)$. Consider the +following example: + +\begin{codeexample}[] +\begin{tikzpicture}[->] + \draw (0,0,0) -- (1,0,0); + \draw (0,0,0) -- (0,1,0); + \draw (0,0,0) -- (0,0,1); +\end{tikzpicture} +\end{codeexample} + + +\subsection{Node Coordinates} +\label{section-node-coordinates} + +In \pgfname\ and in \tikzname\ it is quite easy to define a node that you +wish to reference at a later point. Once you have defined a node, +there are different ways of referencing points of the node. + + +\subsubsection{Named Anchor Coordinates} + +An \emph{anchor coordinate} is a point in a node that you have +previously defined using the node operation. The syntax is +|(|\meta{node name}|.|\meta{anchor}|)|, where \meta{node name} is +the name that was previously used to name the node using the +|name=|\meta{node name} option or the special node name syntax. Here is +an example: + +\begin{codeexample}[] +\begin{tikzpicture} + \node (shape) at (0,2) [draw] {|class Shape|}; + \node (rect) at (-2,0) [draw] {|class Rectangle|}; + \node (circle) at (2,0) [draw] {|class Circle|}; + \node (ellipse) at (6,0) [draw] {|class Ellipse|}; + + \draw (circle.north) |- (0,1); + \draw (ellipse.north) |- (0,1); + \draw[-open triangle 90] (rect.north) |- (0,1) -| (shape.south); +\end{tikzpicture} +\end{codeexample} + +Section~\ref{section-the-shapes} explain which anchors are available +for the basic shapes. + + + + +\subsubsection{Angle Anchor Coordinates} + +In addition to the named anchors, it is possible to use the syntax +\meta{node name}|.|\meta{angle} to name a point of the node's +border. This point is the coordinate where a ray shot from the center +in the given angle hits the border. Here is an example: + +\begin{codeexample}[] +\begin{tikzpicture} + \node (start) [draw,shape=ellipse] {start}; + \foreach \angle in {-90, -80, ..., 90} + \draw (start.\angle) .. controls +(\angle:1cm) and +(-1,0) .. (2.5,0); + \end{tikzpicture} +\end{codeexample} + + +\subsubsection{Anchor-Free Node Coordinates} + +It is also possible to just ``leave out'' the anchor and have \tikzname\ +calculate an appropriate border position for you. Here is an example: + +\begin{codeexample}[] +\begin{tikzpicture}[fill=blue!20] + \draw[style=help lines] (-1,-2) grid (6,3); + \path (0,0) node(a) [ellipse,rotate=10,draw,fill] {An ellipse} + (3,-1) node(b) [circle,draw,fill] {A circle} + (2,2) node(c) [rectangle,rotate=20,draw,fill] {A rectangle} + (5,2) node(d) [rectangle,rotate=-30,draw,fill] {Another rectangle}; + \draw[thick] (a) -- (b) -- (c) -- (d); + \draw[thick,red,->] (a) |- +(1,3) -| (c) |- (b); + \draw[thick,blue,<->] (b) .. controls +(right:2cm) and +(down:1cm) .. (d); +\end{tikzpicture} +\end{codeexample} + +\tikzname\ will be reasonably clever at determining the border points that +you ``mean,'' but, naturally, this may fail in some situations. If +\tikzname\ fails to determine an appropriate border point, the center will +be used instead. + +Automatic computation of anchors works only with the line-to operations +|--|, the vertical/horizontal versions \verb!|-! and \verb!-|!, and +with the curve-to operation |..|. For other path commands, such as +|parabola| or |plot|, the center will be used. If this is not desired, +you should give a named anchor or an angle anchor. + +Note that if you use an automatic coordinate for both the start and +the end of a line-to, as in |--(b)--|, then \emph{two} border +coordinates are computed with a move-to between them. This is usually +exactly what you want. + +If you use relative coordinates together with automatic anchor +coordinates, the relative coordinates are always computed relative to +the node's center, not relative to the border point. Here is an +example: + +\begin{codeexample}[] +\tikz \draw (0,0) node(x) [draw] {Text} + rectangle (1,1) + (x) -- +(1,1); +\end{codeexample} + +Similarly, in the following examples both control points are $(1,1)$: + +\begin{codeexample}[] +\tikz \draw (0,0) node(x) [draw] {X} + (2,0) node(y) {Y} + (x) .. controls +(1,1) and +(-1,1) .. (y); +\end{codeexample} + + +\subsection{Intersection Coordinates} + + +\subsubsection{Intersection of Two Lines} + +Often you wish to specify a point that is on the +intersection of two lines. The first way to specify such an +intersection is the following: You can use the special syntax +\declare{|(intersection of |\meta{$p_1$}|--|\meta{$p_2$}% + | and |\meta{$q_1$}|--|\meta{$q_2$}|)|}. This will yield the +intersection point of the line going through $p_1$ and $p_2$ and the +line through $q_1$ and $q_2$. If the lines do not meet or if they are +identical and arithmetical overflow error will result. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) coordinate (A) -- (3,2) coordinate (B) + (1,2) -- (3,0); + + \fill[red] (intersection of A--B and 1,2--3,0) circle (2pt); +\end{tikzpicture} +\end{codeexample} + +\subsubsection{Intersection of Horizontal and Vertical Lines} + +A frequent special case of intersections is the intersection of a +vertical line going through a point $p$ and a horizontal line going +through some other point $q$. For this situation there is a special, +shorter, syntax: You can say either +\declare{|(|\meta{p}\verb! |- !\meta{q}|)|} or +\declare{|(|\meta{q}\verb! -| !\meta{p}|)|}. + +For example, \verb!(2,1 |- 3,4)! and \verb!(3,4 -| 2,1)! both yield +the same as \verb!(2,4)! (provided the $xy$-coordinate system has not +been modified). + +The most useful application of the syntax is to draw a line up to some +point on a vertical or horizontal line. Here is an example: + +\begin{codeexample}[] +\begin{tikzpicture} + \path (30:1cm) node(p1) {$p_1$} (75:1cm) node(p2) {$p_2$}; + + \draw (-0.2,0) -- (1.2,0) node(xline)[right] {$q_1$}; + \draw (2,-0.2) -- (2,1.2) node(yline)[above] {$q_2$}; + + \draw[->] (p1) -- (p1 |- xline); + \draw[->] (p2) -- (p2 |- xline); + \draw[->] (p1) -- (p1 -| yline); + \draw[->] (p2) -- (p2 -| yline); +\end{tikzpicture} +\end{codeexample} + + + +\subsection{Relative and Incremental Coordinates} + +You can prefix coordinates by |++| to make them ``relative.'' A +coordinate such as |++(1cm,0pt)| means ``1cm to the right of the +previous position.'' Relative coordinates are often useful in +``local'' contexts: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle; + \draw (2,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle; + \draw (1.5,1.5) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle; +\end{tikzpicture} +\end{codeexample} + +Instead of |++| you can also use a single |+|. This also specifies a +relative coordinate, but it does not ``update'' the current point for +subsequent usages of relative coordinates. Thus, you can use this +notation to specify numerous points, all relative to the same +``initial'' point: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle; + \draw (2,0) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle; + \draw (1.5,1.5) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle; +\end{tikzpicture} +\end{codeexample} + +There is one special situation, where relative coordinates are +interpreted differently. If you use a relative coordinate as a control +point of a Bézier curve, the following rule applies: First, a relative +first control point is taken relative to the beginning of the +curve. Second, a relative second control point is taken relative to +the end of the curve. Third, a relative end point of a curve is taken +relative to the start of the curve. + +This special behavior makes it easy to specify that a curve should +``leave or arrives from a certain direction'' at the start or end. In +the following example, the curve ``leaves'' at $30^\circ$ and +``arrives'' at $60^\circ$: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (1,0) .. controls +(30:1cm) and +(60:1cm) .. (3,-1); + \draw[gray,->] (1,0) -- +(30:1cm); + \draw[gray,<-] (3,-1) -- +(60:1cm); +\end{tikzpicture} +\end{codeexample} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex new file mode 100644 index 00000000000..1207f029c38 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex @@ -0,0 +1,248 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Design Principles} + +This section describes the design principles behind the \tikzname\ +frontend, where \tikzname\ means ``\tikzname\ ist \emph{kein} +Zeichenprogramm.'' To use \tikzname, as a \LaTeX\ user say +|\usepackage{tikz}| somewhere in the preamble, as a plain \TeX\ user +say |\input tikz.tex|. \tikzname's job is to make your life easier by +providing an easy-to-learn and easy-to-use syntax for describing +graphics. + +The commands and syntax of \tikzname\ were influenced by several +sources. The basic command names and the notion of path operations is +taken from \textsc{metafont}, the option mechanism comes from +\textsc{pstricks}, the notion of styles is reminiscent of +\textsc{svg}. To make it all work together, some compromises were +necessary. I also added some ideas of my own, like meta-arrows and +coordinate transformations. + +The following basic design principles underlie \tikzname: +\begin{enumerate} +\item Special syntax for specifying points. +\item Special syntax for path specifications. +\item Actions on paths. +\item Key-value syntax for graphic parameters. +\item Special syntax for nodes. +\item Special syntax for trees. +\item Grouping of graphic parameters. +\item Coordinate transformation system. +\end{enumerate} + + + +\subsection{Special Syntax For Specifying Points} + +\tikzname\ provides a special syntax for specifying points and +coordinates. In the simplest case, you provide two \TeX\ dimensions, +separated by commas, in round brackets as in |(1cm,2pt)|. + +You can also specify a point in polar coordinates by using a colon +instead of a comma as in |(30:1cm)|, which means ``1cm in a 30 +degrees direction.'' + +If you do not provide a unit, as in |(2,1)|, you specify a point in +\pgfname's $xy$-coordinate system. By default, the unit $x$-vector +goes 1cm to the right and the unit $y$-vector goes 1cm upward. + +By specifying three numbers as in |(1,1,1)| you specify a point in +\pgfname's $xyz$-coordinate system. + +It is also possible to use an anchor of a previously defined shape +as in |(first node.south)|. + +You can add two plus signs before a coordinate as in +|++(1cm,0pt)|. This means ``1cm to the right of the last point +used.'' This allows you to easily specify relative movements. For +example, |(1,0) ++(1,0) ++(0,1)| specifies the three coordinates +|(1,0)|, then |(2,0)|, and |(2,1)|. + +Finally, instead of two plus signs, you can also add a single +one. This also specifies a point in a relative manner, but it does +not ``change'' the current point used in subsequent relative +commands. For example, |(1,0) +(1,0) +(0,1)| specifies the three +coordinates |(1,0)|, then |(2,0)|, and |(1,1)|. + +\subsection{Special Syntax For Path Specifications} + +When creating a picture using \tikzname, your main job is the +specification of \emph{paths}. A path is a series of straight or curved +lines, which need not be connected. \tikzname\ makes it easy to +specify paths, partly using the syntax of \textsc{metapost}. For +example, to specify a triangular path you use +\begin{codeexample}[code only] +(5pt,0pt) -- (0pt,0pt) -- (0pt,5pt) -- cycle +\end{codeexample} +and you get \tikz \draw (5pt,0pt) -- (0pt,0pt) -- (0pt,5pt) -- cycle; +when you draw this path. + +\subsection{Actions on Paths} + +A path is just a series of straight and curved lines, but it is not +yet specified what should happen with it. One can \emph{draw} a +path, \emph{fill} a path, \emph{shade} it, \emph{clip} it, or do any +combination of these. Drawing (also known as \emph{stroking}) can be +thought of as taking a pen of a certain thickness and moving it +along the path, thereby drawing on the canvas. Filling means that +the interior of the path is filled with a uniform color. Obviously, +filling makes sense only for \emph{closed} paths and a path is +automatically closed prior to filling, if necessary. + +Given a path as in |\path (0,0) rectangle (2ex,1ex);|, you can draw +it by adding the |draw| option as in +|\path[draw] (0,0) rectangle (2ex,1ex);|, which yields \tikz \path[draw] +(0,0) rectangle (2ex,1ex);. The |\draw| command is just an abbreviation for +|\path[draw]|. To fill a path, use the |fill| option or the |\fill| +command, which is an abbreviation for |\path[fill]|. The +|\filldraw| command is an abbreviation for +|\path[fill,draw]|. Shading is caused by the |shade| option (there +are |\shade| and |\shadedraw| abbreviations) and clipping by the +|clip| option. There is is also a |\clip| command, which does the +same as |\path[clip]|, but not commands like |\drawclip|. Use, say, +|\draw[clip]| or |\path[draw,clip]| instead. + +All of these commands can only be used inside |{tikzpicture}| +environments. + +\tikzname\ allows you to use different colors for filling and +stroking. + +\subsection{Key-Value Syntax for Graphic Parameters} +Whenever \tikzname\ draws or fills a path, a large number of graphic +parameters influenced the rendering. Examples include the colors +used, the dashing pattern, the clipping area, the line width, and +many others. In \tikzname, all these options are specified as lists +of so called key-value pairs, as in |color=red|, that are +passed as optional parameters to the path drawing and filling +commands. This usage is similar to \textsc{pstricks}. For +example, the following will draw a thick, red triangle; +\begin{codeexample}[] +\tikz \draw[line width=2pt,color=red] (1,0) -- (0,0) -- (1,0) -- cycle; +\end{codeexample} + +\subsection{Special Syntax for Specifying Nodes} +\tikzname\ introduces a special syntax for adding text or, more +generally, nodes to a graphic. When you specify a path, add nodes as +in the following example: +\begin{codeexample}[] +\tikz \draw (1,1) node {text} -- (2,2); +\end{codeexample} +Nodes are inserted at the current position of +the path, but only \emph{after} the path has been rendered. When +special options are given, as in +|\draw (1,1) node[circle,draw] {text};|, the text is not just put +at the current position. Rather, it is surrounded by a circle and +this circle is ``drawn.'' + +You can add a name to a node for later reference either by using the +option |name=|\meta{node name} or by stating the node name in +parentheses outside the text as in |node[circle](name){text}|. + +Predefined shapes include |rectangle|, |circle|, and |ellipse|, but +it is possible (though a bit challenging) to define new shapes. + +\subsection{Special Syntax for Specifying Trees} + +In addition to the ``node syntax,'' \tikzname\ also introduces a +special syntax for drawing trees. The syntax is intergrated with the +special node syntax and only few new commands need to be remebered. +In essence, a |node| can be followed by any number of children, each +introduced by the keyword |child|. The children are nodes themselves, +each of which may have children in turn. + +\begin{codeexample}[] +\begin{tikzpicture} + \node {root} + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; +\end{tikzpicture} +\end{codeexample} + +Since trees are made up from nodes, it is possible to use options to +modify the way trees are drawn. Here are two examples of the above tree, +redrawn with different options: + +\begin{codeexample}[] +\begin{tikzpicture}[edge from parent fork down] + \tikzstyle{every node}=[fill=red!30,rounded corners] + \tikzstyle{edge from parent}=[red,-o,thick,draw] + \node {root} + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + [parent anchor=east,child anchor=west,grow=east] + \tikzstyle{every node}=[ball color=red,circle,text=white] + \tikzstyle{edge from parent}=[draw,dashed,thick,red] + \node {root} + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; +\end{tikzpicture} +\end{codeexample} + +\subsection{Grouping of Graphic Parameters} + +Graphic parameters should often apply to several path drawing or +filling commands. For example, we may wish to draw numerous lines all +with the same line width of 1pt. For this, we put these commands +in a |{scope}| environment that takes the desired graphic options +as an optional parameter. Naturally, the specified graphic +parameters apply only to the drawing and filling commands inside the +environment. Furthermore, nested |{scope}| environments or +individual drawing commands can override the graphic parameters of +outer |{scope}| environments. In the following example, three red +lines, two green lines, and one blue line are drawn: + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{scope}[color=red] + \draw (0mm,10mm) -- (10mm,10mm); + \draw (0mm, 8mm) -- (10mm, 8mm); + \draw (0mm, 6mm) -- (10mm, 6mm); + \end{scope} + \begin{scope}[color=green] + \draw (0mm, 4mm) -- (10mm, 4mm); + \draw (0mm, 2mm) -- (10mm, 2mm); + \draw[color=blue] (0mm, 0mm) -- (10mm, 0mm); + \end{scope} +\end{tikzpicture} +\end{codeexample} + +The |{tikzpicture}| environment itself also behaves like a +|{scope}| environment, that is, you can specify graphic parameters +using an optional argument. These optional apply to all commands in +the picture. + + +\subsection{Coordinate Transformation System} + +\tikzname\ relies entirely on \pgfname's \emph{coordinate} transformation +system to perform transformations. \pgfname\ also supports +\emph{canvas} transformations, a more low-level transformation system, +but this system is not accessible from \tikzname. There are two reasons +for this: First, the canvas transformation must be used with great +care and often results in ``bad'' graphics with changing line width +and text in wrong sizes. Second, \pgfname\ looses track of where nodes +and shapes are positioned when canvas transformations are used. + +For more details on the difference between coordinate transformations +and canvas transformations see +Section~\ref{section-design-transformations}. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex new file mode 100644 index 00000000000..9eaffdcd086 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex @@ -0,0 +1,1266 @@ +% Copyright 2005 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Syntax for Path Specifications} + +A \emph{path} is a series of straight and curved line segments. It is +specified following a |\path| command and the specification must +follow a special syntax, which is described in the subsections of the +present section. + + +\begin{command}{\path\meta{specification}|;|} + This command is available only inside a |{tikzpicture}| environment. + + The \meta{specification} is a long stream of \emph{path + operations}. Most of these path operations tell \tikzname\ how the path + is build. For example, when you write |--(0,0)|, you use a + \emph{line-to operation} and it means ``continue the path from + wherever you are to the origin.'' + + At any point where \tikzname\ expects a path operation, you can also + give some graphic options, which is a list of options in brackets, + such as |[rounded corners]|. These options can have different + effects: + \begin{enumerate} + \item + Some options take ``immediate'' effect and apply to all subsequent + path operations on the path. For example, the |rounded corners| + option will round all following corners, but not the corners + ``before'' and if the |sharp corners| is given later on the path + (in a new set of brackets), the rounding effect will end. + +\begin{codeexample}[] +\tikz \draw (0,0) -- (1,1) + [rounded corners] -- (2,0) -- (3,1) + [sharp corners] -- (3,0) -- (2,1); +\end{codeexample} + Another example are the transformation options, which also apply + only to subsequent coordinates. + \item + The options that have immediate effect can be ``scoped'' by + putting part of a path in curly braces. For example, the above + example could also be written as follows: + +\begin{codeexample}[] +\tikz \draw (0,0) -- (1,1) + {[rounded corners] -- (2,0) -- (3,1)} + -- (3,0) -- (2,1); +\end{codeexample} + \item + Some options only apply to the path as a whole. For example, the + |color=| option for determining the color used for, say, drawing + the path always applies to all parts of the path. If several + different colors are given for different parts of the path, only + the last one (on the outermost scope) ``wins'': + +\begin{codeexample}[] +\tikz \draw (0,0) -- (1,1) + [color=red] -- (2,0) -- (3,1) + [color=blue] -- (3,0) -- (2,1); +\end{codeexample} + + Most options are of this type. In the above example, we would have + had to ``split up'' the path into several |\path| commands: +\begin{codeexample}[] +\tikz{\draw (0,0) -- (1,1); + \draw [color=red] (2,0) -- (3,1); + \draw [color=blue] (3,0) -- (2,1);} +\end{codeexample} + \end{enumerate} + + By default, the |\path| command does ``nothing'' with the + path, it just ``throws it away.'' Thus, if you write + |\path(0,0)--(1,1);|, nothing is drawn + in your picture. The only effect is that the area occupied by the + picture is (possibly) enlarged so that the path fits inside the + area. To actually ``do'' something with the path, an option like + |draw| or |fill| must be given somewhere on the path. Commands like + |\draw| do this implicitly. + + Finally, it is also possible to give \emph{node specifications} on a + path. Such specifications can come at different locations, but they + are always allowed when a normal path operation could follow. A node + specification starts with |node|. Basically, the effect is to + typeset the node's text as normal \TeX\ text and to place + it at the ``current location'' on the path. The details are explained + in Section~\ref{section-nodes}. + + Note, however, that the nodes are \emph{not} part of the path in any + way. Rather, after everything has been done with the path what is + specified by the path options (like filling and drawing the path due + to a |fill| and a |draw| option somewhere in the + \meta{specification}), the nodes are added in a post-processing + step. + + The following style influences scopes: + \begin{itemize} + \itemstyle{every path} + This style is installed at the beginning of every path. This can + be useful for (temporarily) adding, say, the |draw| option to + everything in a scope. +\begin{codeexample}[] +\begin{tikzpicture}[fill=examplefill] % only sets the color + \tikzstyle{every path}=[draw] % all paths are drawn + \fill (0,0) rectangle +(1,1); + \shade (2,0) rectangle +(1,1); +\end{tikzpicture} +\end{codeexample} + \end{itemize} +\end{command} + + + + +\subsection{The Move-To Operation} + +The perhaps simplest operation is the move-to operation, which is +specified by just giving a coordinate where a path operation is +expected. + +\begin{pathoperation}[noindex]{}{\meta{coordinate}} + \index{empty@\protect\meta{empty} path operation}% + \index{Path operations!empty@\protect\texttt{\meta{empty}}}% + The move-to operation normally starts a path at a certain + point. This does not cause a line segment to be created, but it + specifies the starting point of the next segment. If a path is + already under construction, that is, if several segments have + already been created, a move-to operation will start a new part of the + path that is not connected to any of the previous segments. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) --(2,0) (0,1) --(2,1); +\end{tikzpicture} +\end{codeexample} + + In the specification |(0,0) --(2,0) (0,1) --(2,1)| two move-to + operations are specified: |(0,0)| and |(0,1)|. The other two + operations, namely |--(2,0)| and |--(2,1)| are line-to operations, + described next. +\end{pathoperation} + + +\subsection{The Line-To Operation} + + +\subsubsection{Straight Lines} + +\begin{pathoperation}{--}{\meta{coordinate}} + The line-to operation extends the current path from the current + point in a straight line to the given coordinate. The ``current + point'' is the endpoint of the previous drawing operation or the point + specified by a prior move-to operation. + + You use two minus signs followed by a coordinate in round + brackets. You can add spaces before and after the~|--|. + + When a line-to operation is used and some path segment has just been + constructed, for example by another line-to operation, the two line + segments become joined. This means that if they are drawn, the point + where they meet is ``joined'' smoothly. To appreciate the difference, + consider the following two examples: In the left example, the path + consists of two path segments that are not joined, but that happen to + share a point, while in the right example a smooth join is shown. + +\begin{codeexample}[] +\begin{tikzpicture}[line width=10pt] + \draw (0,0) --(1,1) (1,1) --(2,0); + \draw (3,0) -- (4,1) -- (5,0); + \useasboundingbox (0,1.5); % make bounding box higher +\end{tikzpicture} +\end{codeexample} + +\end{pathoperation} + + +\subsubsection{Horizontal and Vertical Lines} + +Sometimes you want to connect two points via straight lines that are +only horizontal and vertical. For this, you can use two path +construction operations. + +{\catcode`\|=12 +\begin{pathoperation}[noindex]{-|}{\meta{coordinate}} + \index{--1@\protect\texttt{-\protect\pgfmanualbar} path operation}% + \index{Path operations!--1@\protect\texttt{-\protect\pgfmanualbar}}% + This operation means ``first horizontal, then vertical.'' + + \begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) node(a) [draw] {A} (1,1) node(b) [draw] {B}; + \draw (a.north) |- (b.west); + \draw[color=red] (a.east) -| (2,1.5) -| (b.north); +\end{tikzpicture} +\end{codeexample} +\end{pathoperation} +\begin{pathoperation}[noindex]{|-}{\meta{coordinate}} + \index{--2@\protect\texttt{\protect\pgfmanualbar-} path operation}% + \index{Path operations!--2@\protect\texttt{\protect\pgfmanualbar-}}% + This operations means ``first vertical, then horizontal.'' +\end{pathoperation} +} + + +\subsubsection{Snaked Lines} +\label{section-tikz-snakes} + +The line-to operation can not only be used to append straight lines to +the path, but also ``snaked'' lines (called thus because they look a +little bit like snakes seen from above). + +\tikzname\ and \pgfname\ use a concept that I termed \emph{snakes} +for appending such ``squiggly'' lines. A snake specifies a way of +extending a path between two points in a ``fancy manner.'' + +Normally, a snake will just connect the start point to the end point +without starting new subpaths. Thus, a path containing a snaked line +can, nevetheless, still be used for filling. However, this is not +always the case. Some snakes consist of numerous unconnected +segments. ``Lines'' consisting of such snakes cannot be used as the +borders of enclosed areas. + +Here are some examples of snakes in action: + +\begin{codeexample}[] +\begin{tikzpicture}[thick] + \draw (0,3) -- (3,3); + \draw[snake=zigzag] (0,2.5) -- (3,2.5); + \draw[snake=brace] (0,2) -- (3,2); + \draw[snake=triangles] (0,1.5) -- (3,1.5); + \draw[snake=coil,segment length=4pt] (0,1) -- (3,1); + \draw[snake=coil,segment aspect=0] (0,.5) -- (3,.5); + \draw[snake=expanding waves,segment angle=7] (0,0) -- (3,0); +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \filldraw[fill=red!20,snake=bumps] (0,0) rectangle (3,2); +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \filldraw[fill=blue!20] (0,3) + [snake=saw] -- (3,3) + [snake=coil,segment aspect=0] -- (2,1) + [snake=bumps] -| (0,3); +\end{tikzpicture} +\end{codeexample} + +No special path operation is needed to use a snake. Instead, you use +the following option to ``switch on'' snaking: + +\begin{itemize} + \itemoption{snake}\opt{|=|\meta{snake name}} + This option causes the snake \meta{snake name} to be used for + subsequent line-to operations. So, whenever you use the |--| syntax + to specify that a straight line should be added to the path, a snake + to this path will be added instead. Snakes will also be used when + you use the \verb!-|! and \verb!|-! syntax and also when you use the + |rectangle| operation. Snakes will \emph{not} be used when you use + the curve-to operation nor when any other ``curved'' line is added + to the path. + + This option has to be given anew for each path. However, you can + also leave out the \meta{snake name}. In this case, the enclosing + scope's \meta{snake name} is used. Thus, you can specify a + ``standard'' snake name for scope and then just say |\draw[snake]| + every time this snake should actually be used. + + The \meta{snake name} |none| is special. It can be used to switch + off snaking after it has been switched on on a path. + + A bit strangely, no valid \meta{snake names} are defined by + \tikzname\ by default. Instead, you have to include the library + package |pgflibrarysnakes|. This package defines numerous snakes, + see Section~\ref{section-library-snakes} for the complete list. +\end{itemize} + +Most snakes can be configured. For example, for a snake that looks +like a sine curve, you might wish to change the amplitude or the +frequency. There are numerous options that influence these +parameters. Not all options apply to all snakes, see +Section~\ref{section-library-snakes} once more for details. + +\begin{itemize} + \itemoption{gap before snakes}|=|\meta{dimension} + This option allows you to add a certain ``gap'' to the snake at its + beginning. The snake will not start at the current point; instead + the start point of the snake is move be \meta{dimension} in the + direction of the target. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw[snake=zigzag] (0,1) -- ++(3,1); + \draw[snake=zigzag,gap before snake=1cm] (0,0) -- ++(3,1); +\end{tikzpicture} +\end{codeexample} + \itemoption{gap after snake}|=|\meta{dimension} + This option has the same effect as |gap before snake|, only it + affects the end of the snake, which will ``end early.'' + \itemoption{gap around snake}|=|\meta{dimension} + This option sets the gap before and after the gap to + \meta{dimension}. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw[snake=brace] (0,1) -- ++(3,1); + \draw[snake=brace,gap around snake=5mm] (0,0) -- ++(3,1); +\end{tikzpicture} +\end{codeexample} + \itemoption{line before snake}|=|\meta{dimension} + This option works like |gap before snake|, only it will connect the + current point with a straight line to the start of the snake. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw[snake=zigzag] (0,1) -- ++(3,1); + \draw[snake=zigzag,line before snake=1cm] (0,0) -- ++(3,1); +\end{tikzpicture} +\end{codeexample} + \itemoption{line after snake}|=|\meta{dimension} + Works line |gap after snake|, only it adds a straight line. + \itemoption{line around snake}|=|\meta{dimension} + Works line |gap around snake|, only it adds straight lines. + \itemoption{raise snake}|=|\meta{dimension} + This option can be used with all snakes. It will offset the snake by + ``raising'' it by \meta{dimension}. A negative \meta{dimension} will + lower the snake. Raising and lowering is always relative to the line + along which the snake is drawn. Here is an example: +\begin{codeexample}[] +\begin{tikzpicture} + \node (a) {A}; + \node (b) at (2,1) {B}; + \draw (a) -- (b); + \draw[snake=brace] (a) -- (b); + \draw[snake=brace,raise snake=5pt,red] (a) -- (b); +\end{tikzpicture} +\end{codeexample} + \itemoption{mirror snake} + This option causes the snake to be ``reflected along the path.'' + This is best understood by looking at an example: +\begin{codeexample}[] +\begin{tikzpicture} + \node (a) {A}; + \node (b) at (2,1) {B}; + \draw (a) -- (b); + \draw[snake=brace] (a) -- (b); + \draw[snake=brace,mirror snake,red,thick] (a) -- (b); +\end{tikzpicture} +\end{codeexample} + This option can be used with every snake and can be combined with + the |raise snake| option. + \itemoption{segment amplitude}|=|\meta{dimension} + This option sets the ``amplitude'' of the snake. For a snake that is + a sine wave this would be the amplitude of this line. For other + snakes this value typically describes how far the snakes ``rises + above'' or ``falls below'' the path. For some snakes, this value is + ignored. +\begin{codeexample}[] +\begin{tikzpicture} + \node (a) {A} node (b) at (2,1) {B} node (c) at (2,-1) {C}; + \draw[snake=zigzag] (a) -- (b); + \draw[snake=zigzag,segment amplitude=5pt,red,thick] (a) -- (c); +\end{tikzpicture} +\end{codeexample} + \itemoption{segment length}|=|\meta{dimension} + This option sets the length of each ``segment'' of a snake. For a + sine wave this would be the wave length, for other snakes it is the + length of each ``repetitive part'' of the snake. +\begin{codeexample}[] +\begin{tikzpicture} + \node (a) {A} node (b) at (2,1) {B} node (c) at (2,-1) {C}; + \draw[snake=zigzag] (a) -- (b); + \draw[snake=zigzag,segment length=20pt,red,thick] (a) -- (c); +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture} + \node (a) {A} node (b) at (2,1) {B} node (c) at (2,-1) {C}; + \draw[snake=bumps] (a) -- (b); + \draw[snake=bumps,segment length=20pt,red,thick] (a) -- (c); +\end{tikzpicture} +\end{codeexample} + \itemoption{segment object length}|=|\meta{dimension} + This option sets the length of the objects inside each segment of a + snake. This option is only used for snakes in which each segment + contains an object like a triangle or a star. +\begin{codeexample}[] +\begin{tikzpicture} + \node (a) {A} node (b) at (2,1) {B} node (c) at (2,-1) {C}; + \draw[snake=triangles] (a) -- (b); + \draw[snake=triangles,segment object length=8pt,red,thick] (a) -- (c); +\end{tikzpicture} +\end{codeexample} + \itemoption{segment angle}|=|\meta{degrees} + This option sets an angle that is interpreted in a snake-specific + way. For example, the |waves| and |expanding waves| snakes interpret + this as (half the) opening angle of the wave. The |border| snake + uses this value for the angle of the little ticks. +\begin{codeexample}[] +\begin{tikzpicture}[segment amplitude=10pt] + \node (a) {A} node (b) at (2,0) {B}; + \draw[snake=border] (a) -- (b); + \draw[snake=border,segment angle=20,red,thick] (a) -- (b); +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture}[segment amplitude=10pt] + \node (a) {A} node (b) at (2,0) {B}; + \node (a') at (0,-1) {A} node (b') at (2,-1) {B}; + \draw[snake=expanding waves] (a) -- (b); + \draw[snake=expanding waves,segment angle=20,red,thick] (a') -- (b'); +\end{tikzpicture} +\end{codeexample} + \itemoption{segment aspect}|=|\meta{ratio} + This option sets an aspect ratio that is interpreted in a + snake-specific way. For example, for the |coils| snake this + describes the ``direction'' from which the coil is viewed. +\begin{codeexample}[] +\begin{tikzpicture}[segment amplitude=5pt,segment length=5pt] + \node (a) {A} node (b) at (2,1) {B} node (c) at (2,-1) {C}; + \draw[snake=coil] (a) -- (b); + \draw[snake=coil,segment aspect=0,red,thick] (a) -- (c); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +It is possible to define new snakes, but this cannot be done inside +\tikzname. You need to use the command |\pgfdeclaresnake| from the +basic level directly, see Section~\ref{section-base-snakes}. + +The following styles define combinations of segment settings that may +be useful: +\begin{itemize} + \itemstyle{snake triangles 45} + Installs a snake the consists of little triangles with an opening + angle of $45^\circ$. + \itemstyle{snake triangles 60} + Installs a snake the consists of little triangles with an opening + angle of $60^\circ$. + \itemstyle{snake triangles 90} + Installs a snake the consists of little triangles with an opening + angle of $90^\circ$. +\end{itemize} + + + +\subsection{The Curve-To Operation} + +The curve-to operation allows you to extend a path using a Bézier +curve. + +\begin{pathoperation}{..}{\declare{|controls|}\meta{c}\opt{|and|\meta{d}}\declare{|..|\meta{y}}} + This operation extends the current path from the current + point, let us call it $x$, via a curve to a the current point~$y$. + The curve is a cubic Bézier curve. For such a curve, + apart from $y$, you also specify two control points $c$ and $d$. The + idea is that the curve starts at $x$, ``heading'' in the direction + of~$c$. Mathematically spoken, the tangent of the curve at $x$ goes + through $c$. Similarly, the curve ends at $y$, ``coming from'' the + other control point,~$d$. The larger the distance between $x$ and~$c$ + and between $d$ and~$y$, the larger the curve will be. + + If the ``|and|\meta{d}'' part is not given, $d$ is assumed to be + equal to $c$. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[line width=10pt] (0,0) .. controls (1,1) .. (4,0) + .. controls (5,0) and (5,1) .. (4,1); + \draw[color=gray] (0,0) -- (1,1) -- (4,0) -- (5,0) -- (5,1) -- (4,1); +\end{tikzpicture} +\end{codeexample} + + As with the line-to operation, it makes a difference whether two curves + are joined because they resulted from consecutive curve-to or line-to + operations, or whether they just happen to have the same ending: + +\begin{codeexample}[] +\begin{tikzpicture}[line width=10pt] + \draw (0,0) -- (1,1) (1,1) .. controls (1,0) and (2,0) .. (2,0); + \draw (3,0) -- (4,1) .. controls (4,0) and (5,0) .. (5,0); + \useasboundingbox (0,1.5); % make bounding box higher +\end{tikzpicture} +\end{codeexample} +\end{pathoperation} + + +\subsection{The Cycle Operation} + +\begin{pathoperation}{--cycle}{} + This operation adds a straight line from the current + point to the last point specified by a move-to operation. Note that + this need not be the beginning of the path. Furthermore, a smooth join + is created between the first segment created after the last move-to + operation and the straight line appended by the cycle operation. + + Consider the following example. In the left example, two triangles are + created using three straight lines, but they are not joined at the + ends. In the second example cycle operations are used. + +\begin{codeexample}[] +\begin{tikzpicture}[line width=10pt] + \draw (0,0) -- (1,1) -- (1,0) -- (0,0) (2,0) -- (3,1) -- (3,0) -- (2,0); + \draw (5,0) -- (6,1) -- (6,0) -- cycle (7,0) -- (8,1) -- (8,0) -- cycle; + \useasboundingbox (0,1.5); % make bounding box higher +\end{tikzpicture} +\end{codeexample} +\end{pathoperation} + + + +\subsection{The Rectangle Operation} + +A rectangle can obviously be created using four straight lines and a +cycle operation. However, since rectangles are needed so often, a +special syntax is available for them. + +\begin{pathoperation}{rectangle}{\meta{corner}} + When this operation is used, one corner will be the current point, + another corner is given by \meta{corner}, which becomes the new + current point. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) rectangle (1,1); + \draw (.5,1) rectangle (2,0.5) (3,0) rectangle (3.5,1.5) -- (2,0); +\end{tikzpicture} +\end{codeexample} +\end{pathoperation} + + +\subsection{Rounding Corners} + +All of the path construction operations mentioned up to now are +influenced by the following option: +\begin{itemize} + \itemoption{rounded corners}\opt{|=|\meta{inset}} + When this option is in force, all corners (places where a line is + continued either via line-to or a curve-to operation) are replaced by + little arcs so that the corner becomes smooth. + +\begin{codeexample}[] +\tikz \draw [rounded corners] (0,0) -- (1,1) + -- (2,0) .. controls (3,1) .. (4,0); +\end{codeexample} + + The \meta{inset} describes how big the corner is. Note that the + \meta{inset} is \emph{not} scaled along if you use a scaling option + like |scale=2|. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[color=gray,very thin] (10pt,15pt) circle (10pt); + \draw[rounded corners=10pt] (0,0) -- (0pt,25pt) -- (40pt,25pt); +\end{tikzpicture} +\end{codeexample} + + You can switch the rounded corners on and off ``in the middle of + path'' and different corners in the same path can have different + corner radii: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) [rounded corners=10pt] -- (1,1) -- (2,1) + [sharp corners] -- (2,0) + [rounded corners=5pt] -- cycle; +\end{tikzpicture} +\end{codeexample} + +Here is a rectangle with rounded corners: +\begin{codeexample}[] +\tikz \draw[rounded corners=1ex] (0,0) rectangle (20pt,2ex); +\end{codeexample} + + You should be aware, that there are several pitfalls when using this + option. First, the rounded corner will only be an arc (part of a + circle) if the angle is $90^\circ$. In other cases, the rounded + corner will still be round, but ``not as nice.'' + + Second, if there are very short line segments in a path, the + ``rounding'' may cause inadverted effects. In such case it may be + necessary to temporarily switch off the rounding using + |sharp corners|. + + \itemoption{sharp corners} + This options switches off any rounding on subsequent corners of the + path. +\end{itemize} + + + +\subsection{The Circle and Ellipse Operations} + +A circle can be approximated well using four Bézier curves. However, +it is difficult to do so correctly. For this reason, a special syntax +is available for adding such an approximation of a circle to the +current path. + +\begin{pathoperation}{circle}{|(|\meta{radius}|)|} + The center of the circle is given by the current point. The new + current point of the path will remain to be the center of the + circle. +\end{pathoperation} + +\begin{pathoperation}{ellipse}{|(|\meta{half width}| and |\meta{half height}|)|} + Note that you can add spaces after |ellipse|, but you have to place + spaces around |and|. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (1,0) circle (.5cm); + \draw (3,0) ellipse (1cm and .5cm) -- ++(3,0) circle (.5cm) + -- ++(2,-.5) circle (.25cm); +\end{tikzpicture} +\end{codeexample} +\end{pathoperation} + + +\subsection{The Arc Operation} + +The \emph{arc operation} allows you to add an arc to the current +path. +\begin{pathoperation}{arc}{|(|\meta{start angle}|:|\meta{end + angle}|:|\meta{radius}\opt{|/|\meta{half height}}|)|} + The arc operation adds a part of a circle of the given radius + between the given angles. The arc will start at the current point + and will end at the end of the arc. + + \begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) arc (180:90:1cm) -- (2,.5) arc (90:0:1cm); + \draw (4,0) -- +(30:1cm) arc (30:60:1cm) -- cycle; + \draw (8,0) arc (0:270:1cm/.5cm) -- cycle; +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (-1,0) -- +(3.5,0); + \draw (1,0) ++(210:2cm) -- +(30:4cm); + \draw (1,0) +(0:1cm) arc (0:30:1cm); + \draw (1,0) +(180:1cm) arc (180:210:1cm); + \path (1,0) ++(15:.75cm) node{$\alpha$}; + \path (1,0) ++(15:-.75cm) node{$\beta$}; +\end{tikzpicture} +\end{codeexample} +\end{pathoperation} + + +\subsection{The Grid Operation} + +You can add a grid to the current path using the |grid| path +operation. + +\begin{pathoperation}{grid}{\opt{\oarg{options}}\meta{corner}} + This operations adss a grid filling a rectangle whose two corners + are given by \meta{corner} and by the previous coordinate. Thus, the + typical way in which a grid is drawn is |\draw (1,1) grid (3,3);|, + which yields a grid filling the rectangle whose corners are at + $(1,1)$ and $(3,3)$. All coordinate transformations apply to the grid. + +\begin{codeexample}[] +\tikz[rotate=30] \draw[step=1mm] (0,0) grid (2,2); +\end{codeexample} + + The stepping of the grid is governed by the following options: + +\begin{itemize} + \itemoption{step}|=|\meta{dimension} sets the stepping in both the + $x$ and $y$-direction. + \itemoption{xstep}|=|\meta{dimension} sets the stepping in the + $x$-direction. + \itemoption{ystep}|=|\meta{dimension} sets the stepping in the + $y$-direction. +\end{itemize} + + It is important to note that the grid is always ``phased'' such that + it contains the point $(0,0)$ if that point happens to be inside the + rectangle. Thus, the grid does \emph{not} always have an intersection + at the corner points; this occurs only if the corner points are + multiples of the stepping. Note that due to rounding errors, the + ``last'' lines of a grid may be omitted. In this case, you have to + add an epsilon to the corner points. + + The following style is useful for drawing grids: +\begin{itemize} + \itemstyle{help lines} + This style makes lines ``subdued'' by using thin gray lines for + them. However, this style is not installed automatically and you + have to say for example: +\begin{codeexample}[] +\tikz \draw[style=help lines] (0,0) grid (3,3); +\end{codeexample} +\end{itemize} +\end{pathoperation} + + + +\subsection{The Parabola Operation} + +The |parabola| path operation continues the current path with a +parabola. A parabola is a (shifted and scaled) curve defined by the +equation $f(x) = x^2$ and looks like this: \tikz \draw (-1ex,1.5ex) +parabola[parabola height=-1.5ex] +(2ex,0ex);. + +\begin{pathoperation}{parabola}{\opt{\oarg{options}|bend|\meta{bend + coordinate}}\meta{coordinate}} + This operation adds a parabola through the current point and the + given \meta{coordinate}. If the |bend| is given, it specifies where + the bend should go; the \meta{options} can also be used to specify + where the bend is. By default, the bend is at the old current point. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) rectangle (1,1.5) + (0,0) parabola (1,1.5); + \draw[xshift=1.5cm] (0,0) rectangle (1,1.5) + (0,0) parabola[bend at end] (1,1.5); + \draw[xshift=3cm] (0,0) rectangle (1,1.5) + (0,0) parabola bend (.75,1.75) (1,1.5); +\end{tikzpicture} +\end{codeexample} + + The following options influence parabolas: +\begin{itemize} + \itemoption{bend}|=|\meta{coordinate} + Has the same effect as saying |bend|\meta{coordinate} outside the + \meta{options}. The option specifies that the bend of the parabola + should be at the given \meta{coordinate}. You have to take care + yourself that the bend position is a ``valid'' position; which means + that if there is no parabola of the form $f(x) = a x^2 + b x + c$ + that goes through the old current point, the given bend, and the new + current point, the result will not be a parabola. + + There is one special property of the \meta{coordinate}: When a + relative coordinate is given like |+(0,0)|, the position relative + to which this coordinate is ``flexible.'' More precisely, this + position lies somewhere on a line from the old current point to the + new current point. The exact position depends on the next + option. + + \itemoption{bend pos}|=|\meta{fraction} + Specifies where the ``previous'' point is relative to which the bend + is calculated. The previous point will be at the \meta{fraction}th + part of the line from the old current point to the new current + point. + + The idea is the following: If you say |bend pos=0| and + |bend +(0,0)|, the bend will be at the old current point. If you say + |bend pos=1| and |bend +(0,0)|, the bend will be at the new current + point. If you say |bend pos=0.5| and |bend +(0,2cm)| the bend will + be 2cm above the middle of the line between the start and end + point. This is most useful in situations such as the following: +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (-1,0) parabola[bend pos=0.5] bend +(0,2) +(3,0); +\end{tikzpicture} +\end{codeexample} + + In the above example, the |bend +(0,2)| essentially means ``a + parabola that is 2cm high'' and |+(3,0)| means ``and 3cm wide.'' + Since this situation arises often, there is a special shortcut + option: + \itemoption{parabola height}|=|\meta{dimension} This option has the + same effect as if you had written the following instead: + |[bend pos=0.5,bend={+(0pt,|\meta{dimension}|)}]|. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (-1,0) parabola[parabola height=2cm] +(3,0); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +The following styles are useful shortcuts: +\begin{itemize} + \itemstyle{bend at start} This places the bend at the start of a + parabola. It is a shortcut for the following options: + |bend pos=0,bend={+(0,0)}|. + \itemstyle{bend at end} This places the bend at the end of a + parabola. +\end{itemize} +\end{pathoperation} + + +\subsection{The Sine and Cosine Operation} + +The |sin| and |cos| operations are similar to the |parabola| +operation. They, too, can be used to draw (parts of) a sine or cosine +curve. + +\begin{pathoperation}{sin}{\meta{coordinate}} + The effect of |sin| is to draw a scaled and shifted version of a sine + curve in the interval $[0,\pi/2]$. The scaling and shifting is done in + such a way that the start of the sine curve in the interval is at the + old current point and that the end of the curve in the interval is at + \meta{coordinate}. Here is an example that should clarify this: + +\begin{codeexample}[] +\tikz \draw (0,0) rectangle (1,1) (0,0) sin (1,1) + (2,0) rectangle +(1.57,1) (2,0) sin +(1.57,1); +\end{codeexample} +\end{pathoperation} + +\begin{pathoperation}{cos}{\meta{coordinate}} + This operation works similarly, only a cosine in the interval + $[0,\pi/2]$ is drawn. By correctly alternating |sin| and |cos| + operations, you can create a complete sine or cosine curve: + +\begin{codeexample}[] +\begin{tikzpicture}[xscale=1.57] + \draw (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0) sin (5,1); + \draw[color=red] (0,1.5) cos (1,0) sin (2,-1.5) cos (3,0) sin (4,1.5) cos (5,0); +\end{tikzpicture} +\end{codeexample} +\end{pathoperation} + +Note that there is no way to (conveniently) draw an interval on a sine +or cosine curve whose end points are not multiples of $\pi/2$. + + + +\subsection{The Plot Operation} + +The |plot| operation can be used to append a line or curve to the path +that goes through a large number of coordinates. These coordinates are +either given in a simple list of coordinates or they are read from +some file. + +The syntax of the |plot| comes in different versions. + +\begin{pathoperation}{--plot}{\meta{further arguments}} + This operation plots the curve through the coordinates specified in + the \meta{further arguments}. The current (sub)path is simply + continued, that is, a line-to operation to the first point of the + curve is implicitly added. The details of the \meta{further + arguments} will be explained in a moment. +\end{pathoperation} + +\begin{pathoperation}{plot}{\meta{further arguments}} + This operation plots the curve through the coordinates specified in + the \meta{further arguments} by first ``moving'' to the first + coordinate of the curve. +\end{pathoperation} + +The \meta{further arguments} are used in three different ways to +specifying the coordinates of the points to be plotted: + +\begin{enumerate} +\item + \opt{|--|}|plot|\oarg{local options}\declare{|coordinates{|\meta{coordinate + 1}\meta{coordinate 2}\dots\meta{coordinate $n$}|}|} +\item + \opt{|--|}|plot|\oarg{local options}\declare{|file{|\meta{filename}|}|} +\item + \opt{|--|}|plot|\oarg{local options}\declare{|function{|\meta{gnuplot formula}|}|} +\end{enumerate} + +These different ways are explained in the following. + + +\subsubsection{Plotting Points Given Inline} + +In the first two cases, the points are given directly in the \TeX-file +as in the following example: + +\begin{codeexample}[] +\tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,1) (2,1) (10:2cm)}; +\end{codeexample} + +Here is an example showing the difference between |plot| and |--plot|: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) -- (1,1) plot coordinates {(2,0) (4,0)}; + \draw[color=red,xshift=5cm] + (0,0) -- (1,1) -- plot coordinates {(2,0) (4,0)}; +\end{tikzpicture} +\end{codeexample} + + +\subsubsection{Plotting Points Read From an External File} + +The second way of specifying points is to put them in an external +file named \meta{filename}. Currently, the only file format that +\tikzname\ allows is the following: Each line of the \meta{filename} +should contain one line starting with two numbers, separated by a +space. Anything following the two numbers on the line is +ignored. Also, lines starting with a |%| or a |#| are ignored as well +as empty lines. (This is exactly the format that \textsc{gnuplot} +produces when you say |set terminal table|.) If necessary, more +formats will be supported in the future, but it is usually easy to +produce a file containing data in this form. + +\begin{codeexample}[] +\tikz \draw plot[mark=x,smooth] file {plots/pgfmanual-sine.table}; +\end{codeexample} + +The file |plots/pgfmanual-sine.table| reads: +\begin{codeexample}[code only] +#Curve 0, 20 points +#x y type +0.00000 0.00000 i +0.52632 0.50235 i +1.05263 0.86873 i +1.57895 0.99997 i +... +9.47368 -0.04889 i +10.00000 -0.54402 i +\end{codeexample} +It was produced from the following source, using |gnuplot|: +\begin{codeexample}[code only] +set terminal table +set output "../plots/pgfmanual-sine.table" +set format "%.5f" +set samples 20 +plot [x=0:10] sin(x) +\end{codeexample} + +The \meta{local options} of the |plot| operation are local to each +plot and do not affect other plots ``on the same path.'' For example, +|plot[yshift=1cm]| will locally shift the plot 1cm upward. Remember, +however, that most options can only be applied to paths as a +whole. For example, |plot[red]| does not have the effect of making the +plot red. After all, you are trying to ``locally'' make part of the +path red, which is not possible. + +\subsubsection{Plotting a Function} +\label{section-tikz-gnuplot} + +Often, you will want to plot points that are given via a function like +$f(x) = x \sin x$. Unfortunately, \TeX\ does not really have enough +computational power to generate the points on such a function +efficiently (it is a text processing program, after all). However, +if you allow it, \TeX\ can try to call external programs that can +easily produce the necessary points. Currently, \tikzname\ knows how to +call \textsc{gnuplot}. + +When \tikzname\ encounters your operation +|plot[id=|\meta{id}|] function{x*sin(x)}| for +the first time, it will create a file called +\meta{prefix}\meta{id}|.gnuplot|, where \meta{prefix} is |\jobname.| by +default, that is, the name of you main |.tex| file. If no \meta{id} is +given, it will be empty, which is alright, but it is better when each +plot has a unique \meta{id} for reasons explained in a moment. Next, +\tikzname\ writes some initialization code into this file followed by +|plot x*sin(x)|. The initialization code sets up things +such that the |plot| operation will write the coordinates into another +file called \meta{prefix}\meta{id}|.table|. Finally, this table file +is read as if you had said |plot file{|\meta{prefix}\meta{id}|.table}|. + +For the plotting mechanism to work, two conditions must be met: +\begin{enumerate} +\item + You must have allowed \TeX\ to call external programs. This is often + switched off by default since this is a security risk (you might, + without knowing, run a \TeX\ file that calls all sorts of ``bad'' + commands). To enable this ``calling external programs'' a command + line option must be given to the \TeX\ program. Usually, it is + called something like |shell-escape| or |enable-write18|. For + example, for my |pdflatex| the option |--shell-escape| can be + given. +\item + You must have installed the |gnuplot| program and \TeX\ must find it + when compiling your file. +\end{enumerate} + +Unfortunately, these conditions will not always be met. Especially if +you pass some source to a coauthor and the coauthor does not have +\textsc{gnuplot} installed, he or she will have trouble compiling your +files. + +For this reason, \tikzname\ behaves differently when you compile your +graphic for the second time: If upon reaching +|plot[id=|\meta{id}|] function{...}| the file \meta{prefix}\meta{id}|.table| +already exists \emph{and} if the \meta{prefix}\meta{id}|.gnuplot| file +contains what \tikzname\ thinks that it ``should'' contain, the |.table| +file is immediately read without trying to call a |gnuplot| +program. This approach has the following advantages: +\begin{enumerate} +\item + If you pass a bundle of your |.tex| file and all |.gnuplot| and + |.table| files to someone else, that person can \TeX\ the |.tex| + file without having to have |gnuplot| installed. +\item + If the |\write18| feature is switched off for security reasons (a + good idea), then, upon the first compilation of the |.tex| file, the + |.gnuplot| will still be generated, but not the |.table| + file. You can then simply call |gnuplot| ``by hand'' for each + |.gnuplot| file, which will produce all necessary |.table| files. +\item + If you change the function that you wish to plot or its + domain, \tikzname\ will automatically try to regenerate the |.table| + file. +\item + If, out of laziness, you do not provide an |id|, the same |.gnuplot| + will be used for different plots, but this is not a problem since + the |.table| will automatically be regenerated for each plot + on-the-fly. \emph{Note: If you intend to share your files with + someone else, always use an id, so that the file can by typeset + without having \textsc{gnuplot} installed.} Also, having unique ids + for each plot will improve compilation speed since no external + programs need to be called, unless it is really necessary. +\end{enumerate} + +When you use |plot function{|\meta{gnuplot formula}|}|, the \meta{gnuplot + formula} must be given in the |gnuplot| syntax, whose details are +beyond the scope of this manual. Here is the ultra-condensed +essence: Use |x| as the variable and use the C-syntax for normal +plots, use |t| as the variable for parametric plots. Here are some examples: + +\begin{codeexample}[] +\begin{tikzpicture}[domain=0:4] + \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9); + + \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$}; + \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$}; + + \draw[color=red] plot[id=x] function{x} node[right] {$f(x) =x$}; + \draw[color=blue] plot[id=sin] function{sin(x)} node[right] {$f(x) = \sin x$}; + \draw[color=orange] plot[id=exp] function{0.05*exp(x)} node[right] {$f(x) = \frac{1}{20} \mathrm e^x$}; +\end{tikzpicture} +\end{codeexample} + + +The following options influence the plot: + +\begin{itemize} + \itemoption{samples}|=|\meta{number} + sets the number of samples used in the plot. The default is 25. + \itemoption{domain}|=|\meta{start}|:|\meta{end} + sets the domain between which the samples are taken. The default is + |-5:5|. + \itemoption{parametric}\opt{|=|\meta{true or false}} + sets whether the plot is a parametric plot. If true, then |t| must + be used instead of |x| as the parameter and two comma-separated + functions must be given in the \meta{gnuplot formula}. An example is + the following: +\begin{codeexample}[] +\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth] + plot[parametric,id=parametric-example] function{t*sin(t),t*cos(t)}; +\end{codeexample} + + \itemoption{id}|=|\meta{id} + sets the identifier of the current plot. This should be a unique + identifier for each plot (though things will also work if it is not, + but not as well, see the explanations above). The \meta{id} will be + part of a filename, so it should not contain anything fancy like |*| + or |$|.%$ + \itemoption{prefix}|=|\meta{prefix} + is put before each plot file name. The default is |\jobname.|, but + if you have many plots, it might be better to use, say |plots/| and + have all plots placed in a directory. You have to create the + directory yourself. + \itemoption{raw gnuplot} + causes the \meta{gnuplot formula} to be passed on to + \textsc{gnuplot} without setting up the samples or the |plot| + operation. Thus, you could write +\begin{codeexample}[code only] +plot[raw gnuplot,id=raw-example] function{set samples 25; plot sin(x)} +\end{codeexample} + This can be + useful for complicated things that need to be passed to + \textsc{gnuplot}. However, for really complicated situations you + should create a special external generating \textsc{gnuplot} file + and use the |file|-syntax to include the table ``by hand.'' +\end{itemize} + +The following styles influence the plot: +\begin{itemize} + \itemstyle{every plot} + This style is installed in each plot, that is, as if you always said +\begin{codeexample}[code only] + plot[style=every plot,...] +\end{codeexample} + This is most useful for globally setting a prefix for all plots by saying: +\begin{codeexample}[code only] +\tikzstyle{every plot}=[prefix=plots/] +\end{codeexample} +\end{itemize} + + + +\subsubsection{Placing Marks on the Plot} + +As we saw already, it is possible to add \emph{marks} to a plot using +the |mark| option. When this option is used, a copy of the plot +mark is placed on each point of the plot. Note that the marks are +placed \emph{after} the whole path has been drawn/filled/shaded. In +this respect, they are handled like text nodes. + +In detail, the following options govern how marks are drawn: +\begin{itemize} + \itemoption{mark}|=|\meta{mark mnemonic} + Sets the mark to a mnemonic that has previously been defined using + the |\pgfdeclareplotmark|. By default, |*|, |+|, and |x| are available, + which draw a filled circle, a plus, and a cross as marks. Many more + marks become available when the library |pgflibraryplotmarks| is + loaded. Section~\ref{section-plot-marks} lists the available plot + marks. + + One plot mark is special: the |ball| plot mark is available only + it \tikzname. The |ball color| determines the balls's color. Do not use + this option with large number of marks since it will take very long + to render in PostScript. + + \begin{tabular}{lc} + Option & Effect \\\hline \vrule height14pt width0pt + \plotmarkentrytikz{ball} + \end{tabular} + + \itemoption{mark size}|=|\meta{dimension} + Sets the size of the plot marks. For circular plot marks, + \meta{dimension} is the radius, for other plot marks + \meta{dimension} should be about half the width and height. + + This option is not really necessary, since you achieve the same + effect by specifying |scale=|\meta{factor} as a local option, where + \meta{factor} is the quotient of the desired size and the default + size. However, using |mark size| is a bit faster and more natural. + + \itemoption{mark options}|=|\meta{options} + These options are applied to marks when they are drawn. For example, + you can scale (or otherwise transform) the plot mark or set its + color. +\begin{codeexample}[] +\tikz \fill[fill=blue!20] + plot[mark=triangle*,mark options={color=blue,rotate=180}] + file{plots/pgfmanual-sine.table} |- (0,0); +\end{codeexample} +\end{itemize} + + + +\subsubsection{Smooth Plots, Sharp Plots, and Comb Plots} + +There are different things the |plot| operation can do with the points +it reads from a file or from the inlined list of points. By default, +it will connect these points by straight lines. However, you can also +use options to change the behavior of |plot|. + +\begin{itemize} + \itemoption{sharp plot} + This is the default and causes the points to be connected by + straight lines. This option is included only so that you can + ``switch back'' if you ``globally'' install, say, |smooth|. + + \itemoption{smooth} + This option causes the points on the path to be connected using a + smooth curve: + +\begin{codeexample}[] +\tikz\draw plot[smooth] file{plots/pgfmanual-sine.table}; +\end{codeexample} + + Note that the smoothing algorithm is not very intelligent. You will + get the best results if the bending angles are small, that is, less + than about $30^\circ$ and, even more importantly, if the distances + between points are about the same all over the plotting path. + + \itemoption{tension}|=|\meta{value} + This option influences how ``tight'' the smoothing is. A lower value + will result in sharper corners, a higher value in more ``round'' + curves. A value of $1$ results in a circle if four points at + quarter-positions on a circle are given. The default is $0.55$. The + ``correct'' value depends on the details of plot. + +\begin{codeexample}[] +\begin{tikzpicture}[smooth cycle] + \draw plot[tension=0.2] + coordinates{(0,0) (1,1) (2,0) (1,-1)}; + \draw[yshift=-2.25cm] plot[tension=0.5] + coordinates{(0,0) (1,1) (2,0) (1,-1)}; + \draw[yshift=-4.5cm] plot[tension=1] + coordinates{(0,0) (1,1) (2,0) (1,-1)}; +\end{tikzpicture} +\end{codeexample} + + \itemoption{smooth cycle} + This option causes the points on the path to be connected using a + closed smooth curve. + +\begin{codeexample}[] +\tikz[scale=0.5] + \draw plot[smooth cycle] coordinates{(0,0) (1,0) (2,1) (1,2)} + plot coordinates{(0,0) (1,0) (2,1) (1,2)} -- cycle; +\end{codeexample} + + \itemoption{ycomb} + This option causes the |plot| operation to interpret the plotting + points differently. Instead of connecting them, for each point of + the plot a straight line is added to the path from the $x$-axis to the point, + resulting in a sort of ``comb'' or ``bar diagram.'' + +\begin{codeexample}[] +\tikz\draw[ultra thick] plot[ycomb,thin,mark=*] file{plots/pgfmanual-sine.table}; +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture}[ycomb] + \draw[color=red,line width=6pt] + plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)}; + \draw[color=red!50,line width=4pt,xshift=3pt] + plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)}; +\end{tikzpicture} +\end{codeexample} + + \itemoption{xcomb} + This option works like |ycomb| except that the bars are horizontal. + +\begin{codeexample}[] +\tikz \draw plot[xcomb,mark=x] coordinates{(1,0) (0.8,0.2) (0.6,0.4) (0.2,1)}; +\end{codeexample} + + \itemoption{polar comb} + This option causes a line from the origin to the point to be added + to the path for each plot point. + +\begin{codeexample}[] +\tikz \draw plot[polar comb, + mark=pentagon*,mark options={fill=white,draw=red},mark size=4pt] + coordinates {(0:1cm) (30:1.5cm) (160:.5cm) (250:2cm) (-60:.8cm)}; +\end{codeexample} + + + \itemoption{only marks} + This option causes only marks to be shown; no path segments are + added to the actual path. This can be useful for quickly adding some + marks to a path. + +\begin{codeexample}[] +\tikz \draw (0,0) sin (1,1) cos (2,0) + plot[only marks,mark=x] coordinates{(0,0) (1,1) (2,0) (3,-1)}; +\end{codeexample} +\end{itemize} + + + + + +\subsection{The Scoping Operation} + +When \tikzname\ encounters and opening or a closing brace (|{| or~|}|) at +some point where a path operation should come, it will open or close a +scope. All options that can be applied ``locally'' will be scoped +inside the scope. For example, if you apply a transformation like +|[xshift=1cm]| inside the scoped area, the shifting only applies to +the scope. On the other hand, an option like |color=red| does not have +any effect inside a scope since it can only be applied to the path as +a whole. + + +\subsection{The Node Operation} + +You can add nodes to a path using the |node| operation. Since this +operation is quite complex and since the nodes are not really part of +the path itself, there is a separate section dealing with nodes, see +Section~\ref{section-nodes}. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex new file mode 100644 index 00000000000..5339e802d4a --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex @@ -0,0 +1,364 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section[Hierarchical Structures: Package, Environments, Scopes, and Styles] +{Hierarchical Structures:\\ + Package, Environments, Scopes, and Styles} + +The present section explains how your files should be structured when +you use \tikzname. On the top level, you need to include the |tikz| +package. In the main text, each graphic needs to be put in a +|{tikzpicture}| environment. Inside these environments, you can use +|{scope}| environments to create internal groups. Inside the scopes +you use |\path| commands to actually draw something. On all levels +(except for the package level), graphic options can be given that +apply to everything within the environment. + + + +\subsection{Loading the Package} + +\begin{package}{tikz} + This package does not have any options. + + This will automatically load the \pgfname\ package and several other + stuff that \tikzname\ needs (like the |xkeyval| package). + + \pgfname\ needs to know what \TeX\ driver you are intending to use. In + most cases \pgfname\ is clever enough to determine the correct driver + for you; this is true in particular if you \LaTeX. Currently, the only + situation where \pgfname\ cannot know the driver ``by itself'' is when + you use plain \TeX\ or Con\TeX t together with |dvipdfm|. In this case, + you have to write |\def\pgfsysdriver{pgfsys-dvipdfm.def}| + \emph{before} you input |tikz.tex|. +\end{package} + + + +\subsection{Creating a Picture} + +\subsubsection{Creating a Picture Using an Environment} + +The ``outermost'' scope of \tikzname\ is the |{tikzpicture}| +environment. You may give drawing commands only inside this +environment, giving them outside (as is possible in many other +packages) will result in chaos. + +In \tikzname, the way graphics are rendered is strongly influenced by +graphic options. For example, there is an option for setting the color used +for drawing, another for setting the color used for filling, and also +more obscure ones like the option for setting the prefix used in the +filenames of temporary files written while plotting functions using an +external program. The graphic options are nearly always specified in a +so-called key-value style. (The ``nearly always'' refers to the name +of nodes, which can also be specified differently.) All graphic +options are local to the |{tikzpicture}| to which they apply. + +\begin{environment}{{tikzpicture}\opt{\oarg{options}}} + All \tikzname\ commands should be given inside this + environment, except for the |\tikzstyle| command. Unlike other + packages, it is not possible to use, say, |\pgfpathmoveto| outside + this environment and doing so will result in chaos. For \tikzname, + commands like |\path| are only defined inside this environment, so + there is little chance that you will do something wrong here. + + When this environment is encountered, the \meta{options} are + parsed. All options given here will apply to the whole + picture. + + Next, the contents of the environment is processed and the graphic + commands therein are put into a box. Non-graphic text is suppressed + as well as possible, but non-\pgfname\ commands inside a + |{tikzpicture}| environment should not produce any ``output'' since + this may totally scramble the positioning system of the backend + drivers. The suppressing of normal text, by the way, is done by + temporarily switching the font to |\nullfont|. You can, however, + ``escape back'' to normal \TeX\ typesetting. This happens, for + example, when you specify a node. + + At the end of the environment, \pgfname\ tries to make a good guess + at a good guess at the bounding box of the graphic and + then resizes the box such that the box has this size. To ``make its + guess,'' everytime \pgfname\ encounters a coordinate, it updates the + bound box's size such that it encompasses all these + coordinates. This will usually give a good + approximation at the bounding box, but will not always be + accurate. First, the line thickness is not taken into + account. Second, controls points of a curve often lie far + ``outside'' the curve and make the bounding box too large. In this + case, you should use the |[use as bounding box]| option. + + The following option influences the baseline of the resulting + picture: + \begin{itemize} + \itemoption{baseline}\opt{|=|\meta{dimension}} + Normally, the lower end of the picture is put on the baseline of + the surrounding text. For example, when you give the code + |\tikz\draw(0,0)circle(.5ex);|, \pgfname\ will find out that the + lower end of the picture is at $-.5\mathrm{ex}$ and that the upper + end is at $.5\mathrm{ex}$. Then, the lower end will be put on the + baseline, resulting in the following: \tikz\draw(0,0)circle(.5ex);. + + Using this option, you can specify that the picture should be + raised or lowered such that the height \meta{dimension} is on the + baseline. For example, |tikz[baseline=0pt]\draw(0,0)circle(.5ex);| + yields \tikz[baseline=0pt]\draw(0,0)circle(.5ex); since, now, the + baseline is on the height of the $x$-axis. If you omit the + \meta{dimensions}, |0pt| is assumed as default. + + This options is often useful for ``inlined'' graphics as in +\begin{codeexample}[] +$A \mathbin{\tikz[baseline] \draw[->>] (0pt,.5ex) -- (3ex,.5ex);} B$ +\end{codeexample} + + \itemoption{execute at begin picture}|=|\meta{code} + This option can be used to install some code that will be executed + at the beginning of the picture. This option must be + given in the argument of the |{tikzpicture}| environment itself + since this option will not have an effect otherwise. After all, + the picture has already ``started'' later on. + + This option is mainly used in styles like the |every picture| + style to execute certain code at the start of a picture. + + \itemoption{execute at end picture}|=|\meta{code} + This option installs some code that will be executed + at the end of the picture. Using this option multiple times will + cause the code to accumulate. This option must also be given in + the optional argument of the |{tikzpicture}| environment. + +\begin{codeexample}[] +\begin{tikzpicture}[execute at end picture=% + { + \begin{pgfonlayer}{background} + \path[fill=yellow,rounded corners] + (current bounding box.south west) rectangle + (current bounding box.north east); + \end{pgfonlayer} + }] + \node at (0,0) {X}; + \node at (2,1) {Y}; +\end{tikzpicture} +\end{codeexample} + \end{itemize} + + All options ``end'' at the end of the picture. To set an option + ``globally'' you can use the following style: + \begin{itemize} + \itemstyle{every picture} + This style is installed at the beginning of each picture. +\begin{codeexample}[code only] +\tikzstyle{every picture}=[semithick] +\end{codeexample} + \end{itemize} +\end{environment} + +In plain \TeX, you should use instead the following commands: + +\begin{plainenvironment}{{tikzpicture}\opt{\oarg{options}}} +\end{plainenvironment} + + +\subsubsection{Creating a Picture Using a Command} + +The following two commands are used for ``small'' graphics. + +\begin{command}{\tikz\opt{\oarg{options}}\marg{commands}} + This command places the \meta{commands} inside a + |{tikzpicture}| environment and adds a semicolon at the end. This is + just a convenience. + + The \meta{commands} may not contain a paragraph (an empty + line). This is a precaution to ensure that users really use this + command only for small graphics. + + \example |\tikz{\draw (0,0) rectangle (2ex,1ex)}| yields + \tikz{\draw (0,0) rectangle (2ex,1ex);} +\end{command} + + +\begin{command}{\tikz\opt{\oarg{options}}\meta{text}|;|} + If the \meta{text} does not start with an opening brace, the end of + the \meta{text} is the next semicolon that is encountered. + + \example |\tikz \draw (0,0) rectangle (2ex,1ex);| yields + \tikz \draw (0,0) rectangle (2ex,1ex); +\end{command} + + + +\subsubsection{Adding a Background} + +By default, pictures do not have any background, that is, they are +``transparent'' on all parts on which you do not draw +anything. You may instead wish to have a colored background behind +your picture or a black frame around it or lines above and below it or +some other kind of decoration. + +Since backgrounds are often not needed at all, the definition of +styles for adding backgrounds has been put in the library package +|pgflibrarytikzbackgrounds|. This package is documented in +Section~\ref{section-tikz-backgrounds}. + + +\subsection{Using Scopes to Structure a Picture} + +Inside a |{tikzpicture}| environment you can create scopes +using the |{scope}| environment. This environment is available only +inside the |{tikzpicture}| environment, so once more, there is little +chance of doing anything wrong. + +\begin{environment}{{scope}\opt{\oarg{options}}} + All \meta{options} are local to the \meta{environment + contents}. Furthermore, the clipping path is also local to the + environment, that is, any clipping done inside the environment + ``ends'' at its end. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{scope}[red] + \draw (0mm,0mm) -- (10mm,0mm); + \draw (0mm,1mm) -- (10mm,1mm); + \end{scope} + \draw (0mm,2mm) -- (10mm,2mm); + \begin{scope}[green] + \draw (0mm,3mm) -- (10mm,3mm); + \draw (0mm,4mm) -- (10mm,4mm); + \draw[blue] (0mm,5mm) -- (10mm,5mm); + \end{scope} +\end{tikzpicture} +\end{codeexample} + + The following style influences scopes: + \begin{itemize} + \itemstyle{every scope} + This style is installed at the beginning of every scope. I do not + know really know what this might be good for, but who knows? + \end{itemize} + + The following options are useful for scopes: + \begin{itemize} + \itemoption{execute at begin scope}|=|\meta{code} + This option install some code that will be executed + at the beginning of the scope. This option must be + given in the argument of the |{scope}| environment. + + The effect applies only to the current scope, not to subscopes. + + \itemoption{execute at end scope}|=|\meta{code} + This option installs some code that will be executed + at the end of the current scope. Using this option multiple times + will cause the code to accumulate. This option must also be given + in the optional argument of the |{scope}| environment. + + Again, the effect applies only to the current scope, not to subscopes. + \end{itemize} +\end{environment} + + +In plain \TeX, you use the following commands instead: + +\begin{plainenvironment}{{scope}\opt{\oarg{options}}} +\end{plainenvironment} + + + +\subsection{Using Scopes Inside Paths} + +The |\path| command, which is described in much more detail in later +sections, also takes graphic options. These options are local to the +path. Furthermore, it is possible to create local scopes within a +path simply by using curly braces as in +\begin{codeexample}[] +\tikz \draw (0,0) -- (1,1) + {[rounded corners] -- (2,0) -- (3,1)} + -- (3,0) -- (2,1); +\end{codeexample} + +Note that many options apply only to the path as a whole and cannot be +scoped in this way. For example, it is not possible to scope the +|color| of the path. See the explanations in the section on paths for +more details. + +Finally, certain elements that you specify in the argument to the +|\path| command also take local options. For example, a node +specification takes options. In this case, the options apply only to +the node, not to the surrounding path. + + + +\subsection{Using Styles to Manage How Pictures Look} + +There is a way of organizing sets of graphic options ``orthogonally'' +to the normal scoping mechanism. For example, you might wish all your +``help lines'' to be drawn in a certain way like, say, gray and thin +(do \emph{not} dash them, that distracts). For this, you can use +\emph{styles}. + +A style is simply a set of graphic options that is predefined at some +point. Once a style has been defined, it can be used anywhere using +the |style| option: + +\begin{itemize} + \itemoption{style}|=|\meta{style name} + invokes all options that are currently set in the \meta{style + name}. An example of a style is the predefined |help lines| style, + which you should use for lines in the background like grid lines or + construction lines. You can easily define new styles and modify + existing ones. +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) grid +(2,2); + \draw[style=help lines] (2,0) grid +(2,2); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + + +\begin{command}{\tikzstyle\meta{style name}\opt{|+|}|=[|\meta{options}|]|} + This command defines the style \meta{style name}. Whenever it is + used using the |style=|\meta{style name} command, the \meta{options} + will be invoked. It is permissible that a style invokes another + style using the |style=| command inside the \meta{options}, which + allows you to build hierarchies of styles. Naturally, you should + \emph{not} create cyclic dependencies. + + If the style already has a predefined meaning, it will + unceremoniously be redefined without a warning. +\begin{codeexample}[] +\tikzstyle{help lines}=[blue!50,very thin] +\begin{tikzpicture} + \draw (0,0) grid +(2,2); + \draw[style=help lines] (2,0) grid +(2,2); +\end{tikzpicture} +\end{codeexample} + + If the optional |+| is given, the options are \emph{added} to the + existing definition: +\begin{codeexample}[] +\tikzstyle{help lines}+=[dashed]% aaarghhh!!! +\begin{tikzpicture} + \draw (0,0) grid +(2,2); + \draw[style=help lines] (2,0) grid +(2,2); +\end{tikzpicture} +\end{codeexample} +\end{command} + +It is also possible to set a style using an option: +\begin{itemize} + \itemoption{set style}|={|\marg{style name}\opt{|+|}|=[|\meta{options}|]}| + This option has the same effect as saying |\tikzstyle| before the + argument of the option. +\begin{codeexample}[] +\begin{tikzpicture}[set style={{help lines}+=[dashed]}] + \draw (0,0) grid +(2,2); + \draw[style=help lines] (2,0) grid +(2,2); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex new file mode 100644 index 00000000000..e118bf98449 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex @@ -0,0 +1,832 @@ +% Copyright 2005 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Nodes} + +\label{section-nodes} + +\subsection{Nodes and Their Shapes} + +\tikzname\ offers an easy way of adding so-called \emph{nodes} to your +pictures. In the simplest case, a node is just some text that is +placed at some coordinate. However, a node can also have a border +drawn around it or have a more complex background and +foreground. Indeed, some nodes do not have a text at all, but consist +solely of the background. You can name nodes so that you can reference +their coordinates later in the picture. However, \emph{nodes cannot be + referenced across different pictures}. + +There are no special \TeX\ commands for adding a node to a picture; rather, +there is path operation called |node| for this. Nodes are created +whenever \tikzname\ encounters |node| or |coordinate| at a point on a +path where it would expect a normal path operation (like |-- (1,1)| or +|sin (1,1)|). It is also possible to give node specifications +\emph{inside} certain path operations as explained later. + +The node operation is typically followed by some options, which apply +only to the node. Then, you can optionally \emph{name} the node by +providing a name in round braces. Lastly, for the |node| operation you +must provide some label text for the node in curly braces, while for +the |coordinate| operation you may not. The node is placed at the +current position of the path \emph{after the path has been + drawn}. Thus, all nodes are drawn ``on top'' of the path and +retained until the path is complete. If there are several nodes on a +path, they are drawn on top of the path in the order they are +encountered. + +\begin{codeexample}[] +\tikz \fill[fill=examplefill] + (0,0) node {first node} + -- (1,1) node {second node} + -- (0,2) node {third node}; +\end{codeexample} + +The syntax for specifying nodes is the following: +\begin{pathoperation}{node}{\opt{|[|\meta{options}|]|}\opt{|(|\meta{name}|)|}% + \opt{|at(|\meta{coordinate}|)|}\opt{\marg{text}}} + The effect of |at| is to place the node at the coordinate given + after |at| and not, as would normally be the case, at the last + position. The |at| syntax is not available when a node is given + inside a path operation (it would not make any sense, there). + + The |(|\meta{name}|)| is a name for later reference and it is + optional. You may also add the option |name=|\meta{name} to the + \meta{option} list; it has the same effect. + + \begin{itemize} + \itemoption{name}|=|\meta{node name} + assigns a name to the node for later reference. Since this is a + ``high-level'' name (drivers never know of it), you can use spaces, + number, letters, or whatever you like when naming a node. Thus, you + can name a node just |1| or perhaps |start of chart| or even + |y_1|. Your node name should \emph{not} contain any punctuation like + a dot, a comma, or a colon since these are used to detect what kind + of coordinate you mean when you reference a node. + \end{itemize} + + The \meta{options} is an optional list of options that \emph{apply + only to the node} and have no effect outside. The other way round, + most ``outside'' options also apply to the node, but not all. For + example, the ``outside'' rotation does not apply to nodes (unless some + special options are used, sigh). Also, the outside path action, like + |draw| or |fill|, never applies to the node and must be given in the + node (unless some special other options are used, deep sigh). + + As mentioned before, we can add a border and even a background to a + node: +\begin{codeexample}[] +\tikz \fill[fill=examplefill] + (0,0) node {first node} + -- (1,1) node[draw] {second node} + -- (0,2) node[fill=red!20,draw,double,rounded corners] {third node}; +\end{codeexample} + + The ``border'' is actually just a special case of a much more general + mechanism. Each node has a certain \emph{shape} which, by default, is + a rectangle. However, we can also ask \tikzname\ to use a circle shape + instead or an ellipse shape (you have to include |pgflibraryshapes| for + the latter shape): + +\begin{codeexample}[] +\tikz \fill[fill=examplefill] + (0,0) node{first node} + -- (1,1) node[ellipse,draw] {second node} + -- (0,2) node[circle,fill=red!20] {third node}; +\end{codeexample} + + In the future, there might be much more complicated shapes available + such as, say, a shape for a resistor or a shape for a state of a + finite automaton or a shape for a \textsc{uml} class. Unfortunately, + creating new shapes is a bit tricky and makes it necessary to use the + basic layer directly. Life is hard. + + To select the shape of a node, the following option is used: + \begin{itemize} + \itemoption{shape}|=|\meta{shape name} + select the shape either of the current node or, when this option is + not given inside a node but somewhere outside, the shape of all + nodes in the current scope.% + \indexoption{\meta{shape name}} + + Since this option is used often, you can leave out the + |shape=|. When \tikzname\ encounters an option like |circle| + that it does not know, it will, after everything else has failed, + check whether this option is the name of some shape. If so, that + shape is selected as if you had said |shape=|\meta{shape name}. + + By default, the following shapes are available: |rectangle|, + |circle|, |coordinate|, and, when the package |pgflibraryshapes| is + loaded, also |ellipse|. Details of these shapes, like their anchors + and size options, are discussed in Section~\ref{section-the-shapes}. + \end{itemize} + + The following styles influences how nodes are rendered: + \begin{itemize} + \itemstyle{every node} + This style is installed at the beginning of every node. +\begin{codeexample}[] +\begin{tikzpicture} + \tikzstyle{every node}=[draw] + \draw (0,0) node {A} -- (1,1) node {B}; +\end{tikzpicture} +\end{codeexample} + + \itemstyle{every \meta{shape} node} + These styles are installed at the beginning of a node of a given + \meta{shape}. For example, |every rectangle node| is used for + rectangle nodes, and so on. +\begin{codeexample}[] +\begin{tikzpicture} + \tikzstyle{every rectangle node}=[draw] + \tikzstyle{every circle node}= [draw,double] + \draw (0,0) node[rectangle] {A} -- (1,1) node[circle] {B}; +\end{tikzpicture} +\end{codeexample} + \end{itemize} +\end{pathoperation} + +The is a special syntax for specifying ``light-weighed'' nodes: + +\begin{pathoperation}{coordinate}{\opt{|[|\meta{options}|]|}|(|\meta{name}|)|\opt{|at(|\meta{coordinate}|)|}} + This has the same effect as + + |node[shape=coordinate][|\meta{options}|](|\meta{name}|)at(|\meta{coordinate}|){}|, + + where the |at| part might be missing. +\end{pathoperation} + + + +\subsection{Multi-Part Nodes} + +Most nodes just have a single simple text label. However, nodes of a +more complicated shapes might be made up from several \emph{node + parts}. For example, in automata theory a so-called Moore state has +a state name, drawn in the upper part of the state circle, and an +output text, drawn in the lower part of the state circle. These two +parts are quite independent. Similarly, a \textsc{uml} class shape +would have a name part, a method part, and an attributes +part. Different molecule shape might use parts for the different atoms +to be drawn at the different positions, and so on. + +Both \pgfname\ and \tikzname\ support such multipart nodes. On the +lower level, \pgfname\ provides a system for specifying that a shape +consists of several parts. On the \tikzname\ level, you specify the +different node parts by using the following command: + +\begin{command}{\nodepart\marg{part name}} + This command can only be used inside the \meta{text} argument of a + |node| path operation. It works a little bit like a |\part| command + in \LaTeX. It will stop the typesetting of whatever node part was + typeset until now and then start putting all following text into the + node part named \meta{part name}---until another |\partname| is + encountered or until the node \meta{text} ends. + +\begin{codeexample}[] +\begin{tikzpicture} + \node [state with output,draw,double,fill=red!20] + { + % No \nodepart has been used, yet. So, the following is put in the + % ``text'' node part by default. + $q_1$ + \nodepart{output} % Ok, end ``text'' part, start ``output'' part + $00$ + }; % output part ended. +\end{tikzpicture} +\end{codeexample} + + You will have to lookup which parts are defined by a shape. + + The following styles influences node parts: + \begin{itemize} + \itemstyle{every \meta{part name} node part} + This style is installed at the beginning of every node part named + \meta{part name}. +\begin{codeexample}[] +\tikzstyle{every output node part}=[red] +\tikz \node [state with output,draw] {$q_1$ \nodepart{output} $00$}; +\end{codeexample} + \end{itemize} +\end{command} + + + +\subsection{Options for the Text in Nodes} + +The simplest option for the text in nodes is its color. Normally, this +color is just the last color installed using |color=|, possibly +inherited from another scope. However, it is possible to specificly +set the color used for text using the following option: + +\begin{itemize} + \itemoption{text}|=|\meta{color} + Sets the color to be used for text labels. A |color=| option + will immediately override this option. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[red] (0,0) -- +(1,1) node[above] {red}; + \draw[text=red] (1,0) -- +(1,1) node[above] {red}; + \draw (2,0) -- +(1,1) node[above,red] {red}; +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +Next, you may wish to adjust the font used for the text. Use the +following option for this: +\begin{itemize} + \itemoption{font}|=|\meta{font commands} + Sets the font used for text labels. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[font=\itshape] (1,0) -- +(1,1) node[above] {italic}; +\end{tikzpicture} +\end{codeexample} + A perhaps more useful example is the following: + +\begin{codeexample}[] +\tikzstyle{every text node part}=[font=\itshape] +\tikzstyle{every output node part}=[font=\footnotesize] +\tikzstyle{every state with output node}=[draw] +\tikz \node [state with output] {state \nodepart{output} output}; +\end{codeexample} +\end{itemize} + + +Normally, when a node is typeset, all the text you give in the braces +is but in one long line (in an |\hbox|, to be precise) and the node +will become as wide as necessary. + +You can change this behaviour using the following options. They allow +you to limit the width of a node (naturally, at the expense of its +height). + +\begin{itemize} + \itemoption{text width}|=|\meta{dimension} + This option will put the text of a node in a box of the given width + (more precisely, in a |{minipage}| of this width; for plain \TeX\ a + rudimentary ``minipage emulation'' is used). + + If the node text is not as wide as \meta{dimension}, it will + nevertheless be put in a box of this width. If it is larger, line + breaking will be done. + + By default, when this option is given, a ragged right border will be + used. This is sensible since, typically, these boxes are narrow and + justifying the text looks ugly. +\begin{codeexample}[] +\tikz \draw (0,0) node[fill=examplefill,text width=3cm] + {This is a demonstration text for showing how line breaking works.}; +\end{codeexample} + \itemoption{text justified} + causes the text to be justified instead of (right)ragged. Use this + only with pretty broad nodes. +{% +\hbadness=10000 +\begin{codeexample}[] +\tikz \draw (0,0) node[fill=examplefill,text width=3cm,text justified] + {This is a demonstration text for showing how line breaking works.}; +\end{codeexample} +} + In the above example, \TeX\ complains (rightfully) about three very + badly typeset lines. (For this manual I asked \TeX\ to stop + complaining by using |\hbadness=10000|, but this is a foul deed, + indeed.) + \itemoption{text ragged} + causes the text to be typeset with a ragged right. This uses the + original plain \TeX\ definition of a ragged right border, in which + \TeX\ will try to balance the right border as well as possible. This + is the default. +\begin{codeexample}[] +\tikz \draw (0,0) node[fill=examplefill,text width=3cm,text ragged] + {This is a demonstration text for showing how line breaking works.}; +\end{codeexample} + \itemoption{text badly ragged} + causes the right border to be ragged in the \LaTeX-style, in which + no balancing occurs. This looks ugly, but it may be useful for very + narrow boxes and when you wish to avoid hyphenations. +\begin{codeexample}[] +\tikz \draw (0,0) node[fill=examplefill,text width=3cm,text badly ragged] + {This is a demonstration text for showing how line breaking works.}; +\end{codeexample} + \itemoption{text centered} + centers the text, but tries to balance the lines. +\begin{codeexample}[] +\tikz \draw (0,0) node[fill=examplefill,text width=3cm,text centered] + {This is a demonstration text for showing how line breaking works.}; +\end{codeexample} + \itemoption{text badly centered} + centers the text, without balancing the lines. +\begin{codeexample}[] +\tikz \draw (0,0) node[fill=examplefill,text width=3cm,text badly centered] + {This is a demonstration text for showing how line breaking works.}; +\end{codeexample} +\end{itemize} + + + +\subsection{Placing Nodes Using Anchors} + +When you place a node at some coordinate, the node is centered on this +coordinate by default. This is often undesirable and it would be +better to have the node to the right or above the actual coordinate. + +\pgfname\ uses a so-called anchoring mechanism to give you a very fine +control over the placement. The idea is simple: Imaging a node of +rectangular shape of a certain size. \pgfname\ defines numerous anchor +positions in the shape. For example to upper right corner is called, +well, not ``upper right anchor,'' but the |north east| anchor of the +shape. The center of the shape has an anchor called |center| on top of +it, and so on. Here are some examples (a complete list is given in +Section~\ref{section-the-shapes}). + +\medskip\noindent +\begin{tikzpicture} + \path node[minimum height=2cm,minimum width=5cm,fill=blue!25](x) {Big node}; + \fill (x.north) circle (2pt) node[above] {|north|} + (x.north east) circle (2pt) node[above] {|north east|} + (x.north west) circle (2pt) node[above] {|north west|} + (x.west) circle (2pt) node[left] {|west|} + (x.east) circle (2pt) node[right] {|east|} + (x.base) circle (2pt) node[below] {|base|}; +\end{tikzpicture} + +Now, when you place a node at a certain coordinate, you can ask \tikzname\ +to place the node shifted around in such a way that a certain +anchor is at the coordinate. In the following example, we ask \tikzname\ +to shift the first node such that its |north east| anchor is at +coordinate |(0,0)| and that the |west| anchor of the second node is at +coordinate |(1,1)|. + +\begin{codeexample}[] +\tikz \draw (0,0) node[anchor=north east] {first node} + rectangle (1,1) node[anchor=west] {second node}; +\end{codeexample} + +Since the default anchor is |center|, the default behaviour is to +shift the node in such a way that it is centered on the current +position. + +\begin{itemize} + \itemoption{anchor}|=|\meta{anchor name} + causes the node to be shifted such that it's anchor \meta{anchor + name} lies on the current coordinate. + + The only anchor that is present in all shapes is |center|. However, + most shapes will at least define anchors in all ``compass + directions.'' Furthermore, the standard shapes also define a |base| + anchor, as well as |base west| and |base east|, for placing things on + the baseline of the text. + + The standard shapes also define a |mid| anchor (and |mid west| and + |mid east|). This anchor is half the height of the character ``x'' + above the base line. This anchor is useful for vertically centering + multiple nodes that have different heights and depth. Here is an + example: +\begin{codeexample}[] +\begin{tikzpicture}[scale=3,transform shape] + % First, center alignment -> wobbles + \draw[anchor=center] (0,1) node{x} -- (0.5,1) node{y} -- (1,1) node{t}; + % Second, base alignment -> no wobble, but too high + \draw[anchor=base] (0,.5) node{x} -- (0.5,.5) node{y} -- (1,.5) node{t}; + % Third, mid alignment + \draw[anchor=mid] (0,0) node{x} -- (0.5,0) node{y} -- (1,0) node{t}; +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +Unfortunately, while perfectly logical, it is often rather +counter-intuitive that in order to place a node \emph{above} a given +point, you need to specify the |south| anchor. For this reason, there +are some useful options that allow you to select the standard anchors +more intuitively: +\begin{itemize} + \itemoption{above}\opt{|=|\meta{offset}} + does the same as |anchor=south|. If the \meta{offset} is specified, + the node is additionally shifted upwards by the given + \meta{offset}. +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[above] {above}; +\end{codeexample} +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[above=2pt] {above}; +\end{codeexample} + \itemoption{above left}\opt{|=|\meta{offset}} + does the same as |anchor=south east|. If the \meta{offset} is + specified, the node is additionally shifted upwards and right by + \meta{offset}. +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[above left] {above left}; +\end{codeexample} +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[above left=2pt] {above left}; +\end{codeexample} + \itemoption{above right}\opt{|=|\meta{offset}} + does the same as |anchor=south west|. +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[above right] {above right}; +\end{codeexample} + \itemoption{left}\opt{|=|\meta{offset}} + does the same as |anchor=east|. +\begin{codeexample}[] +\tikz \fill (0,0) circle (2pt) node[left] {left}; +\end{codeexample} + \itemoption{right}\opt{|=|\meta{offset}} + does the same as |anchor=west|. + \itemoption{below}\opt{|=|\meta{offset}} + does the same as |anchor=north|. + \itemoption{below left}\opt{|=|\meta{offset}} + does the same as |anchor=north east|. + \itemoption{below right}\opt{|=|\meta{offset}} + does the same as |anchor=north west|. +\end{itemize} + + +\subsection{Transformations} + +It is possible to transform nodes, but, by default, transformations do +not apply to nodes. The reason is that you usually do \emph{not} want +your text to be scaled or rotated even if the main graphic is +transformed. Scaling text is evil, rotating slightly less so. + +However, sometimes you \emph{do} wish to transform a node, for +example, it certainly sometimes makes sense to rotate a node by +90 degrees. There are two ways in which you can achieve this: + +\begin{enumerate} +\item + You can use the following option: + \begin{itemize} + \itemoption{transform shape} + causes the current ``external'' transformation matrix to be + applied to the shape. For example, if you said + |\tikz[scale=3]| and then say |node[transform shape] {X}|, you + will get a ``huge'' X in your graphic. + \end{itemize} +\item + You can give transformation option \emph{inside} the option list of + the node. \emph{These} transformations always apply to the node. +\begin{codeexample}[] +\begin{tikzpicture} + \tikzstyle{every node}=[draw] + \draw[style=help lines] (0,0) grid (3,2); + \draw (1,0) node{A} + (2,0) node[rotate=90,scale=1.5] {B}; + \draw[rotate=30] (1,0) node{A} + (2,0) node[rotate=90,scale=1.5] {B}; + \draw[rotate=60] (1,0) node[transform shape] {A} + (2,0) node[transform shape,rotate=90,scale=1.5] {B}; +\end{tikzpicture} +\end{codeexample} +\end{enumerate} + + + +\subsection{Placing Nodes on a Line or Curve} + +Until now, we always placed node on a coordinate that is mentioned in +the path. Often, however, we wish to place nodes on ``the middle'' of +a line and we do not wish to compute these coordinates ``by hand.'' +To facilitate such placements, \tikzname\ allows you to specify that a +certain node should be somewhere ``on'' a line. There are two ways of +specifying this: Either explicitly by using the |pos| option or +implicitly by placing the node ``inside'' a path operation. These two +ways are described in the following. + + + +\subsubsection{Explicit Use of the Position Option} + +\label{section-pos-option} + +\begin{itemize} + \itemoption{pos}|=|\meta{fraction} + When this option is given, the node is not anchored on the last + coordinate. Rather, it is anchored on some point on the line from + the previous coordinate to the current point. The \meta{fraction} + dictates how ``far'' on the line the point should be. A + \meta{fraction} or 0 is the previous coordinate, 1 is the current + one, everything else is in between. In particular, 0.5 is the + middle. + + Now, what is ``the previous line''? This depends on the previous + path construction operation. + + In the simplest case, the previous path operation was a ``line-to'' + operation, that is, a |--|\meta{coordinate} operation: +\begin{codeexample}[] +\tikz \draw (0,0) -- (3,1) + node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10}; +\end{codeexample} + + The next case is the curve-to operation (the |..| operation). In this + case, the ``middle'' of the curve, that is, the position |0.5| is + not necessarily the point at the exact half distance on the + line. Rather, it is some point at ``time'' 0.5 of a point traveling + from the start of the curve, where it is at time 0, to the end of + the curve, which it reaches at time 0.5. The ``speed'' of the point + depends on the length of the support vectors (the vectors that + connect the start and end points to the control points). The exact + math is a bit complicated (depending on your point of view, of + course); you may wish to consult a good book on computer graphics + and Bézier curves if you are intrigued. +\begin{codeexample}[] + \tikz \draw (0,0) .. controls +(right:3.5cm) and +(right:3.5cm) .. (0,3) + \foreach \p in {0,0.125,...,1} {node[pos=\p]{\p}}; +\end{codeexample} + + Another interesting case are the horizontal/vertical line-to operations + \verb!|-! and \verb!-|!. For them, the position (or time) |0.5| is + exactly the corner point. + +\begin{codeexample}[] +\tikz \draw (0,0) |- (3,1) + node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10}; +\end{codeexample} + +\begin{codeexample}[] +\tikz \draw (0,0) -| (3,1) + node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10}; +\end{codeexample} + + For all other path construction operations, \emph{the position + placement does not work}, currently. This will hopefully change in + the future (especially for the arc operation). + \itemoption{sloped} + This option causes the node to be rotated such that a horizontal + line becomes a tangent to the curve. The rotation will always be + done in such a way that text is never ``upside down.'' If you really + need upside down text, use |[rotate=180]|. +\begin{codeexample}[] +\tikz \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3) + \foreach \p in {0,0.25,...,1} {node[sloped,above,pos=\p]{\p}}; +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture}[->] + \draw (0,0) -- (2,0.5) node[midway,sloped,above] {$x$}; + \draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$}; +\end{tikzpicture} +\end{codeexample} +\end{itemize} + + +There exist styles for specifying positions a bit less ``technically'': +\begin{itemize} + \itemstyle{midway} + is set to |pos=0.5|. +\begin{codeexample}[] +\tikz \draw (0,0) .. controls +(up:2cm) and +(left:3cm) .. (1,5) + node[at end] {|at end|} + node[very near end] {|very near end|} + node[near end] {|near end|} + node[midway] {|midway|} + node[near start] {|near start|} + node[very near start] {|very near start|} + node[at start] {|at start|}; +\end{codeexample} + \itemstyle{near start} + is set to |pos=0.25|. + \itemstyle{near end} + is set to |pos=0.75|. + \itemstyle{very near start} + is set to |pos=0.125|. + \itemstyle{very near end} + is set to |pos=0.875|. + \itemstyle{at start} + is set to |pos=0|. + \itemstyle{at end} + is set to |pos=1|. +\end{itemize} + + +\subsubsection{Implicit Use of the Position Option} + +When you wish to place a node on the line |(0,0) -- (1,1)|, +it is natural to specify the node not following the |(1,1)|, but +``somewhere in the middle.'' This is, indeed, possible and you can +write |(0,0) -- node{a} (1,1)| to place a node midway between |(0,0)| and +|(1,1)|. + +What happens is the following: The syntax of the line-to path +operation is actually |--| +\opt{|node|\meta{node specification}}\meta{coordinate}. (It is even +possible to give multiple nodes in this way.) When the optional +|node| is encountered, that is, +when the |--| is directly followed by |node|, then the +specification(s) are read and ``stored away.'' Then, after the +\meta{coordinate} has finally been reached, they are inserted again, +but with the |pos| option set. + +There are two things to note about this: When a node specification is +``stored,'' its catcodes become fixed. This means that you cannot use +overly complicated verbatim text in them. If you really need, say, a +verbatim text, you will have to put it in a normal node following the +coordinate and add the |pos| option. + +Second, which |pos| is chosen for the node? The position is inherited +from the surrounding scope. However, this holds only for nodes +specified in this implicit way. Thus, if you add the option +|[near end]| to a scope, this does not mean that \emph{all} nodes given +in this scope will be put on near the end of lines. Only the nodes +for which an implicit |pos| is added will be placed near the +end. Typically, this is what you want. Here are some examples that +should make this clearer: + +\begin{codeexample}[] +\begin{tikzpicture}[near end] + \draw (0cm,4em) -- (3cm,4em) node{A}; + \draw (0cm,3em) -- node{B} (3cm,3em); + \draw (0cm,2em) -- node[midway] {C} (3cm,2em); + \draw (0cm,1em) -- (3cm,1em) node[midway] {D} ; +\end{tikzpicture} +\end{codeexample} + +Like the line-to operation, the curve-to operation |..| also allows you to +specify nodes ``inside'' the operation. After both the first |..| and +also after the second |..| you can place node specifications. Like for +the |--| operation, these will be collected and then reinserted after +the operation with the |pos| option set. + + +\subsection{Connecting Nodes} + +Once you have defined a node and given it a name, you can use this +name to reference it. This can be done in two ways, see also +Section~\ref{section-node-coordinates}. Suppose you have said +|\path(0,0) node(x) {Hello World!};| in order to define a node named |x|. +\begin{enumerate} +\item + Once the node |x| has been defined, you can use + |(x.|\meta{anchor}|)| wherever you would normally use a normal + coordinate. This will yield the position at which the given + \meta{anchor} is in the picture. Note that transformations do not + apply to this coordinate, that is, |(x.north)| will be the northern + anchor of |x| even if you have said |scale=3| or |xshift=4cm|. This + is usually what you would expect. +\item + You can also just use |(x)| as a coordinate. In most cases, this + gives the same coordinate as |(x.center)|. Indeed, if the |shape| of + |x| is |coordinate|, then |(x)| and |(x.center)| have exactly the + same effect. + + However, for most other shapes, some path construction operations like + |--| try to be ``clever'' when this they are asked to draw a line + from such a coordinate or to such a coordinate. When you say + |(x)--(1,1)|, the |--| path operation will not draw a line from the center + of |x|, but \emph{from the border} of |x| in the direction going + towards |(1,1)|. Likewise, |(1,1)--(x)| will also have the line + end on the border in the direction coming from |(1,1)|. + + In addition to |--|, the curve-to path operation |..| and the path + operations \verb!-|! and \verb!|-! will also handle nodes without + anchors correctly. Here is an example, see also + Section~\ref{section-node-coordinates}: +\begin{codeexample}[] +\begin{tikzpicture} + \path (0,0) node (x) {Hello World!} + (3,1) node[circle,draw](y) {$\int_1^2 x \mathrm d x$}; + + \draw[->,blue] (x) -- (y); + \draw[->,red] (x) -| node[near start,below] {label} (y); + \draw[->,orange] (x) .. controls +(up:1cm) and +(left:1cm) .. node[above,sloped] {label} (y); +\end{tikzpicture} +\end{codeexample} +\end{enumerate} + + + + + +\subsection{Predefined Shapes} +\label{section-the-shapes} + +\pgfname\ and \tikzname\ define three shapes, by default: +\begin{itemize} +\item + |rectangle|, +\item + |circle|, and +\item + |coordinate|. +\end{itemize} +By loading library packages, you can define more shapes. Currently, +the package |pgflibraryshapes| defines +\begin{itemize} +\item + |ellipse|. +\end{itemize} + +The exact behaviour of these shapes differs, shapes defined for more +special purposes (like a, say, transistor shape) will have even more +custom behaviors. However, there are some options that apply to most +shapes: +\begin{itemize} + \itemoption{inner sep}|=|\meta{dimension} + An additional (invisible) separation space of \meta{dimension} will + be added inside the shape, between the text and the shape's + background path. The effect is as if you had added appropriate + horizontal and vertical skips at the beginning and end of the text + to make it a bit ``larger.'' The default |inner sep| is the size of + a normal space. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) node[inner sep=0pt,draw] {tight} + (0cm,2em) node[inner sep=5pt,draw] {loose} + (0cm,4em) node[fill=examplefill] {default}; +\end{tikzpicture} +\end{codeexample} + \itemoption{inner xsep}|=|\meta{dimension} + Specifies the inner separation in the $x$-direction, only. + \itemoption{inner ysep}|=|\meta{dimension} + Specifies the inner separation in the $y$-direction, only. + + \itemoption{outer sep}|=|\meta{dimension} + This option adds an additional (invisible) separation space of + \meta{dimension} outside the background path. The main effect of + this option is that all anchors will move a little ``to the + outside.'' + + The default for this option is half the line width. When the default + is used and when the background path is draw, the anchors will lie + exactly on the ``outside border'' of the path (not on the path + itself). When the shape is filled, but not drawn, this may not be + desirable. In this case, the |outer sep| should be set to zero + point. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[line width=5pt] + (0,0) node[outer sep=0pt,fill=examplefill] (f) {filled} + (2,0) node[inner sep=.5\pgflinewidth+2pt,draw] (d) {drawn}; + + \draw[->] (1,-1) -- (f); + \draw[->] (1,-1) -- (d); +\end{tikzpicture} +\end{codeexample} + \itemoption{outer xsep}|=|\meta{dimension} + Specifies the outer separation in the $x$-direction, only. + \itemoption{outer ysep}|=|\meta{dimension} + Specifies the outer separation in the $y$-direction, only. + + \itemoption{minimum height}|=|\meta{dimension} + This option ensures that the height of the shape (including the + inner, but ignoring the outer separation) will be at least + \meta{dimension}. Thus, if the text plus the inner separation is not + at least as large as \meta{dimension}, the shape will be enlarged + appropriately. However, if the text is already larger than + \meta{dimension}, the shape will not be shrunk. +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) node[minimum height=1cm,draw] {1cm} + (2,0) node[minimum height=0cm,draw] {0cm}; +\end{tikzpicture} +\end{codeexample} + + \itemoption{minimum width}|=|\meta{dimension} + same as |minimum height|, only for the width. +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) node[minimum height=2cm,minimum width=3cm,draw] {$3 \times 2$}; +\end{tikzpicture} +\end{codeexample} + \itemoption{minimum size}|=|\meta{dimension} + sets both the minimum height and width at the same time. +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) node[minimum size=2cm,draw] {square}; + \draw (0,-2) node[minimum size=2cm,draw,circle] {circle}; +\end{tikzpicture} +\end{codeexample} +\end{itemize} + +\label{section-tikz-coordinate-shape} +The |coordinate| shape is handled in a special way by \tikzname. When +a node |x| whose shape is |coordinate| is used as a coordinate |(x)|, +this has the same effect as if you had said |(x.center)|. None of the +special ``line shortening rules'' apply in this case. This can be +useful since, normally, the line shortening causes paths to be +segmented and they cannot be used for filling. Here is an example that +demonstrates the difference: +\begin{codeexample}[] +\begin{tikzpicture} + \tikzstyle{every node}=[draw] + \path[yshift=1.5cm,shape=rectangle] + (0,0) node(a1){} (1,0) node(a2){} + (1,1) node(a3){} (0,1) node(a4){}; + \filldraw[fill=examplefill] (a1) -- (a2) -- (a3) -- (a4); + + \path[shape=coordinate] + (0,0) coordinate(b1) (1,0) coordinate(b2) + (1,1) coordinate(b3) (0,1) coordinate(b4); + \filldraw[fill=examplefill] (b1) -- (b2) -- (b3) -- (b4); +\end{tikzpicture} +\end{codeexample} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex new file mode 100644 index 00000000000..874d1682df9 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex @@ -0,0 +1,337 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Transformations} + +\pgfname\ has a powerful transformation mechanism that is similar to +the transformation capabilities of \textsc{metafont}. The present +section explains how you can access it in \tikzname. + + +\subsection{The Different Coordinate Systems} + +It is a long process from a coordinate like, say, $(1,2)$ or +$(1\mathrm{cm},5\,mathrm{pt})$, to the position a point is finally +placed on the display or paper. In order to find out where the point +should go, it is constantly ``transformed,'' which means that it is +mostly shifted around and possibly rotated, slanted, scaled, and +otherwise mutilated. + +In detail, (at least) the following transformations are applied to a +coordinate like $(1,2)$ before a point on the screen is chosen: +\begin{enumerate} +\item + \pgfname\ interprets a coordinate like $(1,2)$ in its + $xy$-coordinate system as ``add the current $x$-vector once and the + current $y$-vector twice to obtain the new point.'' +\item + \pgfname\ applies its coordinate transformation matrix to the + resulting coordinate. This yields the final position of the point + inside the picture. +\item + The backend driver (like |dvips| or |pdftex|) adds transformation + commands such the coordinate is shifted to the correct position in + \TeX's page coordinate system. +\item + \textsc{pdf} (or PostScript) apply the canvas transformation + matrix to the point, which can once more change the position on the + page. +\item + The viewer application or the printer applies the device + transformation matrix to transform the coordinate to its final pixel + coordinate on the screen or paper. +\end{enumerate} + +In reality, the process is even more involved, but the above should +give the idea: A point is constantly transformed by changes of the +coordinate system. + +In \tikzname, you only have access to the first two coordinate systems: +The $xy$-coordinate system and the coordinate transformation matrix +(these will be explained later). \pgfname\ also allows you to change +the canvas transformation matrix, but you have to use commands of +the core layer directly to do so and you ``better know what you are +doing'' when you do this. The moment you start modifying the +canvas matrix, \pgfname\ immediately looses track of all +coordinates and shapes, anchors, and bounding box computations will no +longer work. + + +\subsection{The Xy- and Xyz-Coordinate Systems} + +The first and easiest coordinate systems are \pgfname's $xy$- and +$xyz$-coordinate systems. The idea is very simple: Whenever you +specify a coordinate like |(2,3)| this means $2v_x + 3v_y$, where +$v_x$ is the current \emph{$x$-vector} and $v_y$ is the current +\emph{$y$-vector}. Similarly, the coordinate |(1,2,3)| means $v_x + +2v_y + 3v_z$. + +Unlike other packages, \pgfname\ does not insist that $v_x$ actually +has a $y$-component of $0$, that is, that it is a horizontal +vector. Instead, the $x$-vector can point anywhere you +want. Naturally, \emph{normally} you will want the $x$-vector to point +horizontally. + +One undesirable effect of this flexibility is that it is not possible +to provide mixed coordinates as in $(1,2\mathrm{pt})$. Life is hard. + +To change the $x$-, $y$-, and $z$-vectors, you can use the following +options: + +\begin{itemize} +\itemoption{x}|=|\meta{dimension} + Sets the $x$-vector of \pgfname's $xyz$-coordinate system to point + \meta{dimension} to the right, that is, to + $(\meta{dimension},0pt)$. The default is 1cm. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) -- +(1,0); + \draw[x=2cm,color=red] (0,0.1) -- +(1,0); +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\tikz \draw[x=1.5cm] (0,0) grid (2,2); +\end{codeexample} + +The last example shows that the size of steppings in grids, just like +all other dimensions, are not affected by the $x$-vector. After all, +the $x$-vector is only used to determine the coordinate of the upper +right corner of the grid. +\itemoption{x}|=|\meta{coordinate} + Sets the $x$-vector of \pgfname's $xyz$-coordinate system to the + specified \meta{coordinate}. If \meta{coordinate} contains a comma, + it must be put in braces. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) -- (1,0); + \draw[x={(2cm,0.5cm)},color=red] (0,0) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + You can use this, for example, to exchange the meaning of the $x$- and + $y$-coordinate. + +\begin{codeexample}[] +\begin{tikzpicture}[smooth] + \draw plot coordinates{(1,0) (2,0.5) (3,0) (3,1)}; + \draw[x={(0cm,1cm)},y={(1cm,0cm)},color=red] + plot coordinates{(1,0) (2,0.5) (3,0) (3,1)}; +\end{tikzpicture} +\end{codeexample} + +\itemoption{y}|=|\meta{value} + Works like the |x=| option, only if \meta{value} is a dimension, the + resulting vector points to $(0,\meta{value})$. +\itemoption{z}|=|\meta{value} + Works like the |z=| option, but now a dimension is means the point + $(\meta{value},\meta{value})$. + +\begin{codeexample}[] +\begin{tikzpicture}[z=-1cm,->,thick] + \draw[color=red] (0,0,0) -- (1,0,0); + \draw[color=blue] (0,0,0) -- (0,1,0); + \draw[color=orange] (0,0,0) -- (0,0,1); +\end{tikzpicture} +\end{codeexample} +\end{itemize} + + + +\subsection{Coordinate Transformations} + +\pgfname\ and \tikzname\ allow you to specify \emph{coordinate + transformations}. Whenever you specify a coordinate as in |(1,0)| or +|(1cm,1pt)| or |(30:2cm)|, this coordinate is first +``reduced'' to a position of the form ``$x$ points to the right and + $y$ points upwards.'' For example, |(1in,5pt)| is reduced to +``$72\frac{72}{100}$ points to the right and 5 points upwards'' and +|(90:100pt)| means ``0pt to the right and 100 points upwards.'' + +The next step is to apply the current \emph{coordinate transformation + matrix} to the coordinate. For example, the coordinate +transformation matrix might currently be set such that it adds a +certain constant to the $x$ value. Also, it might be setup such that +it, say, exchanges the $x$ and $y$ value. In general, any +``standard'' transformation like translation, rotation, slanting, or +scaling or any combination thereof is possible. (Internally, \pgfname\ +keeps track of a coordinate transformation matrix very much like the +concatenation matrix used by \textsc{pdf} or PostScript.) + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (0,0) rectangle (1,0.5); + \begin{scope}[xshift=1cm] + \draw [red] (0,0) rectangle (1,0.5); + \draw[yshift=1cm] [blue] (0,0) rectangle (1,0.5); + \draw[rotate=30] [orange] (0,0) rectangle (1,0.5); + \end{scope} +\end{tikzpicture} +\end{codeexample} + +The most important aspect of the coordinate transformation matrix is +\emph{that it applies to coordinates only!} In particular, the +coordinate transformation has no effect on things like the line width +or the dash pattern or the shading angle. In certain cases, it is not +immediately clear whether the coordinate transformation matrix +\emph{should} apply to a certain dimension. For example, should the +coordinate transformation matrix apply to grids? (It does.) And what +about the size of arced corners? (It does not.) The general rule is +``If there is no `coordinate' involved, even `indirectly,' the matrix +is not applied.'' However, sometimes, you simply have to try or look +it up in the documentation whether the matrix will be applied. + +Setting the matrix cannot be done directly. Rather, all you can do is +to ``add'' another transformation to the current matrix. However, all +transformations are local to the current \TeX-group. All +transformations are added using graphic options, which are described +below. + +Transformations apply immediately when they are encountered ``in the +middle of a path'' and they apply only to the coordinates on the path +following the transformation option. + +\begin{codeexample}[] +\tikz \draw (0,0) rectangle (1,0.5) [xshift=2cm] (0,0) rectangle (1,0.5); +\end{codeexample} + +A final word of warning: You should refrain from using ``aggressive'' +transformations like a scaling of a factor of 10000. The reason is +that all transformations are done using \TeX, which has a fairly low +accuracy. Furthermore, in certain situations it is necessary that +\tikzname\ \emph{inverts} the current transformation matrix and this will +fail if the transformation matrix is badly conditioned or even +singular (if you do not know what singular matrices are, you are blessed). + +\begin{itemize} + \itemoption{shift}|={|\meta{coordinate}|}| + adds the \meta{coordinate} to all coordinates. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[shift={(1,1)},blue] (0,0) -- (1,1) -- (1,0); + \draw[shift={(30:1cm)},red] (0,0) -- (1,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + \itemoption{xshift}|=|\meta{dimension} + adds \meta{dimension} to the $x$ value of all coordinates. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[xshift=2cm,blue] (0,0) -- (1,1) -- (1,0); + \draw[xshift=-10pt,red] (0,0) -- (1,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + \itemoption{yshift}|=|\meta{dimension} + adds \meta{dimension} to the $y$ value of all coordinates. + + \itemoption{scale}|=|\meta{factor} + multiplies all coordinates by the given \meta{factor}. The + \meta{factor} should not be excessively large in absolute terms or + very near to zero. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[scale=2,blue] (0,0) -- (1,1) -- (1,0); + \draw[scale=-1,red] (0,0) -- (1,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + \itemoption{xscale}|=|\meta{factor} + multiplies only the $x$-value of all coordinates by the given + \meta{factor}. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[xscale=2,blue] (0,0) -- (1,1) -- (1,0); + \draw[xscale=-1,red] (0,0) -- (1,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + \itemoption{yscale}|=|\meta{factor} + multiplies only the $y$-value of all coordinates by \meta{factor}. + + \itemoption{xslant}|=|\meta{factor} + slants the coordinate horizontally by the given \meta{factor}: +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[xslant=2,blue] (0,0) -- (1,1) -- (1,0); + \draw[xslant=-1,red] (0,0) -- (1,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + \itemoption{yslant}|=|\meta{factor} + slants the coordinate vertically by the given \meta{factor}: +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[yslant=2,blue] (0,0) -- (1,1) -- (1,0); + \draw[yslant=-1,red] (0,0) -- (1,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + \itemoption{rotate}|=|\meta{degree} + rotates the coordinate system by \meta{degree}: +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[rotate=40,blue] (0,0) -- (1,1) -- (1,0); + \draw[rotate=-20,red] (0,0) -- (1,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + \itemoption{rotate around}|={|\meta{degree}|:|\meta{coordinate}|}| + rotates the coordinate system by \meta{degree} around the point + \meta{coordinate}. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[rotate around={40:(1,1)},blue] (0,0) -- (1,1) -- (1,0); + \draw[rotate around={-20:(1,1)},red] (0,0) -- (1,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + \itemoption{cm}|={|\meta{$a$}|,|\meta{$b$}|,|\meta{$c$}|,|\meta{$d$}|,|\meta{coordinate}|}| + applies the following transformation to all coordinates: Let $(x,y)$ + be the coordinate to be transformed and let \meta{coordinate} + specify the point $(t_x,t_y)$. Then the new coordinate is given by + $\left(\begin{smallmatrix} a & b \\ c & d\end{smallmatrix}\right) + \left(\begin{smallmatrix} x \\ y \end{smallmatrix}\right) + + \left(\begin{smallmatrix} t_x \\ t_y + \end{smallmatrix}\right)$. Usually, you do not use this option + directly. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[cm={1,1,0,1,(0,0)},blue] (0,0) -- (1,1) -- (1,0); + \draw[cm={0,1,1,0,(1cm,1cm)},red] (0,0) -- (1,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + \itemoption{reset cm} + completely resets the coordinate transformation matrix to the + identity matrix. This will destroy not only the transformations + applied in the current scope, but also all transformations inherited + from surrounding scopes. Do not use this option. +\end{itemize} + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex new file mode 100644 index 00000000000..fb53ead11d1 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex @@ -0,0 +1,745 @@ +% Copyright 2005 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Making Trees Grow} + +\label{section-trees} + + +\subsection{Introduction to the Child Operation} + +\emph{Trees} are a common way of visualizing hierarchical +structures. A simple tree looks like this: +\begin{codeexample}[] +\begin{tikzpicture} + \node {root} + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; +\end{tikzpicture} +\end{codeexample} + +Admittedly, in reality trees are more likely to grow \emph{upward} and +not downward as above. You can tell whether the author of a paper is a +mathematician or a computer scientist by looking at the direction +their trees grow. A computer scientist's trees will grow downward +while a mathematician's tree will grow upward. Naturally, the +\emph{correct} way is the mathematician's way, which can be specify as +follows: +\begin{codeexample}[] +\begin{tikzpicture} + \node {root} [grow'=up] + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; +\end{tikzpicture} +\end{codeexample} + +In \tikzname, trees are specified by adding \emph{children} to a +node on a path using the |child| operation: + +\begin{pathoperation}{child}{\opt{\oarg{options}}% + \opt{|foreach|\meta{variables}|in|\marg{values}}\opt{\marg{child path}}} + This operation should directly follow a completed |node| operation + or another |child| operation, although it is permissible that the + first |child| operation is preceded by options (we will come to + that). + + When a |node| operation like |node {X}| is followed by |child|, + \tikzname\ starts counting the number of child nodes that follow the + original |node {X}|. For this, it scans the input and stores away each + |child| and its arguments until it reaches a path operation that is + not a |child|. Note that this will fix the character codes of all + text inside the child arguments, which means, in essence, that you + cannot use verbatim text inside the nodes inside a |child|. Sorry. + + Once the children have been collected and counted, \tikzname\ starts + generating the child nodes. For each child of a parent node + \tikzname\ computes an appropriate position where the child is + placed. For each child, the coordinate system is transformed so that + the origin is at this position. Then the \meta{child path} is + drawn. Typically, the child path just consists of a |node| + specification, which results in a node being drawn at the child's + position. Finally, an edge is drawn from the first node in the + \meta{child path} to the parent node. + + The optional |foreach| part (note that there is no backslash before + |foreach|) allows you to specify multiple children in a single + |child| command. The idea is the following: A |\foreach| statement + is (internally) used to iterate over the list of \meta{values}. For + each value in this list, a new |child| is added to the node. The + syntax for \meta{variables} and for \meta{values} is the same as for + the |\foreach| statement, see Section~\ref{section-foreach}. For + example, when you say +\begin{codeexample}[code only] +node {root} child [red] foreach \name in {1,2} {node {\name}} +\end{codeexample} + the effect will be the same as if you had said +\begin{codeexample}[code only] +node {root} child[red] {node {1}} child[ref] {node {2}} +\end{codeexample} + When you write +\begin{codeexample}[code only] +node {root} child[\pos] foreach \name/\pos in {1/left,2/right} {node[\pos] {\name}} +\end{codeexample} + the effect will be the same as for +\begin{codeexample}[code only] +node {root} child[left] {node[left] {1}} child[right] {node[right] {2}} +\end{codeexample} + + You can nest things as in the following example: +\begin{codeexample}[] +\begin{tikzpicture}[level distance=4mm] + \tikzstyle{level 1}=[sibling distance=8mm] + \tikzstyle{level 2}=[sibling distance=4mm] + \tikzstyle{level 3}=[sibling distance=2mm] + \coordinate + child foreach \x in {0,1} + {child foreach \y in {0,1} + {child foreach \z in {0,1}}}; +\end{tikzpicture} +\end{codeexample} + + The details and options for this operation are described in the rest + of this present section. +\end{pathoperation} + + + +\subsection{Child Paths and the Child Nodes} + +For each |child| of a root node, its \meta{child path} is inserted at +a specific location in the picture (the placement rules are discussed +in Section~\ref{section-tree-placement}). The first node in the +\meta{child path}, if it exists, is special and called the \emph{child + node}. If there is no first node in the \meta{child path}, that is, +if the \meta{child path} is missing (including the curly braces) or if +it does not start with |node| or with |coordinate|, then an empty +child node of shape |coordinate| is automatically added. + +Consider the example |\node {x} child {node {y}} child;|. For the +first child, the \meta{child path} has the child node |node {y}|. For +the second child, no child node is specified and, thus, it is just +|coordinate|. + +As for any normal node, you can give the child node a name, shift it +around, or use options to influence how it is rendered. +\begin{codeexample}[] +\begin{tikzpicture} + \node[rectangle,draw] {root} + child {node[circle,draw] (left node) {left}} + child {node[ellipse,draw] (right node) {right}}; + \draw[dashed,->] (left node) -- (right node); +\end{tikzpicture} +\end{codeexample} + +In many cases, the \meta{child path} will just consist of a +specification of a child node and, possibly, children of this child +node. However, the node specification may be followed by arbitrary +other material that will be added to the picture, transformed to the +child's coordinate system. For your convenience, a move-to |(0,0)| +operation is inserted automatically at the beginning of the path. Here +is an example: + +\begin{codeexample}[] +\begin{tikzpicture} + \node {root} + child {[fill] circle (2pt)} + child {[fill] circle (2pt)}; +\end{tikzpicture} +\end{codeexample} + + +At the end of the \meta{child path} you may add a special path +operation called |edge from parent|. If this operation is not given by +yourself somewhere on the path, it will be automatically added at the +end. This option causes a connecting edge from the parent node to the +child node to be added to the path. By giving options to this +operation you can influence how the edge is rendered. Also, nodes +following the |edge from parent| operation will be placed on this +edge, see Section~\ref{section-edge-from-parent} for details. + +To sum up: +\begin{enumerate} +\item + The child path starts with a node specification. If it is not there, + it is added automatically. +\item + The child path ends with a |edge from parent| operation, possibly + followed by nodes to be put on this edge. If the operation is not + given at the end, it is added automatically. +\end{enumerate} + + + +\subsection{Naming Child Nodes} + +Child nodes can be named like any other node using either the |name| +option or the special syntax in which the name of the node is placed +in round parentheses between the |node| operation and the node's +text. + +If you do not assign a name to a child node, \tikzname\ will +automatically assign a name as follows: Assume that the name of the +parent node is, say, |parent|. (If you did not assign a +name to the parent, \tikzname\ will do so itself, but that name will +not be user-accessible.) The first child +of |parent| will be named |parent-1|, the second child is named +|parent-2|, and so on. + +This naming convention works recursively. If the second child +|parent-2| has children, then the first of these children will be +called |parent-2-1| and the second |parent-2-2| and so on. + +If you assign a name to a child node yourself, no name is generated +automatically (the node does not have two names). However, ``counting +continues,'' which means that the third child of |parent| is called +|parent-3| independently of whether you have assigned names to the +first and/or second child of |parent|. + +Here is an example: + +\begin{codeexample}[] +\begin{tikzpicture} + \node (root) {root} + child + child { + child {coordinate (special)} + child + }; + \node at (root-1) {root-1}; + \node at (root-2) {root-2}; + \node at (special) {special}; + \node at (root-2-2) {root-2-2}; +\end{tikzpicture} +\end{codeexample} + +\subsection{Specifying Options for Trees and Children} + +Each |child| may have its own \meta{options}, which apply to ``the +whole child,'' including all of its grandchildren. Here is an +example: + +\begin{codeexample}[] +\begin{tikzpicture}[thick] + \tikzstyle{level 2}=[sibling distance=10mm] + \coordinate + child[red] {child child} + child[green] {child child[blue]}; +\end{tikzpicture} +\end{codeexample} + +The options of the root node have no effect on the children since +the options of a node are always ``local'' to that node. Because of +this, the edges in the following tree are black, not red. + +\begin{codeexample}[] +\begin{tikzpicture}[thick] + \node [red] {root} + child + child; +\end{tikzpicture} +\end{codeexample} + This raises the problem of how to set options for \emph{all} + children. Naturally, you could always set options for the whole path + as in |\path [red] node {root} child child;| but this is bothersome + in some situations. Instead, it is easier to give the options + \emph{before the first child} as follows: +\begin{codeexample}[] +\begin{tikzpicture}[thick] + \node [red] {root} + [green] % option applies to all children + child + child; +\end{tikzpicture} +\end{codeexample} + +Here is the set of rules: +\begin{enumerate} +\item + Options for the whole tree are given before the root node. +\item + Options for the root node are given directly to the |node| operation + of the root. +\item + Options for all children can be given between the root node and the + first child. +\item + Options applying to a specific child path are given as options to + the |child| operation. +\item + Options applying to the node of a child, but not to the whole child + path, are given as options to the |node| command inside the + \meta{child path}. +\end{enumerate} + +\begin{codeexample}[code only] +\begin{tikzpicture} + \path + [...] % Options apply to the whole tree + node[...] {root} % Options apply to the root node only + [...] % Options apply to all children + child[...] % Options apply to this child and all its children + { + node[...] {} % Options apply to the child node only + ... + } + child[...] % Options apply to this child and all its children + ; +\end{tikzpicture} +\end{codeexample} + +There are additional styles that influence how children are rendered: +\begin{itemize} + \itemstyle{every child} + This style is used at the beginning of each child, as if you had + given the options to the |child| operation. + \itemstyle{every child node} + This style is used at the beginning of each child node in addition + to the |every node| style. + \itemstyle{level \meta{number}} + This style is used at the beginning of each set of children, where + \meta{number} is the current level in the current tree. For example, + when you say |\node {x} child child;|, then the style |level 1| is + used before the first |child|. If this first |child| has children + itself, then |level 2| would be used for them. + +\begin{codeexample}[] +\begin{tikzpicture} + \tikzstyle{level 1}=[sibling distance=20mm] + \tikzstyle{level 2}=[sibling distance=5mm] + \node {root} + child { child child } + child { child child child }; +\end{tikzpicture} +\end{codeexample} +\end{itemize} + + + + +\subsection{Placing Child Nodes} + +\label{section-tree-placement} + +Perhaps the most difficult part in drawing a tree is the correct +layout of the children. Typically, the children have different sizes +and it is not easy to arrange them in such a manner that not too much +space is wasted, the children do not overlap, and they are either +evenly spaced or their centers are evenly distributed. Calculating +good positions is especially difficult since a good position for the +first child may depend on the size of the last child. + +In \tikzname, a comparatively simple approach is taken to placing the +children. In order to compute a child's position, all that is taken +into account is the number of the current child in the list of +children and the number of children in this list. Thus, if a node has +five children, then there is a fixed position for the first child, a +position for the second child, and so on. These positions \emph{do not + depend on the size of the children} and, hence, children can easily +overlap. However, since you can use options to shift individual +children a bit, this is not as great a problem as it may seem. + +Although the placement of the children only depends on their number in +the list of children and the total number of children, everything else +about the placement is highly configurable. You can change the +distance between children (appropriately called the +|sibling distance|) and the distance between levels of the tree. These +distances may change from level to level. The direction in which the +tree grows can be changed globally and for parts of the tree. You can +even specify your own ``growth function'' to arrange children on a +circle or along special lines or curves. + +The default growth function works as follows: Assume that we are given +a node and five children. These children will be placed on a line with +their centers (or, more generally, with their anchors) spaced apart by +the current |sibling distance|. The line is +orthogonal to the current \emph{direction of growth}, which is set +with the |grow| and |grow'| option (the latter option reverses the +ordering of the children). The distance from the line to the parent node +is given by the |level distance|. + +{\catcode`\|=12 +\begin{codeexample}[] +\begin{tikzpicture} + \path [help lines] + node (root) {root} + [grow=-10] + child {node {1}} + child {node {2}} + child {node {3}} + child {node {4}}; + + \draw[|<->|,thick] (root-1.center) + -- node[above,sloped] {sibling distance} (root-2.center); + + \draw[|<->|,thick] (root.center) + -- node[above,sloped] {level distance} +(-10:\tikzleveldistance); +\end{tikzpicture} +\end{codeexample} +} + +Here is a detailed description of the options: +\begin{itemize} + \itemoption{level distance}|=|\meta{distance} + This option allows you to change the distance between different + levels of the tree, more precisely, between the parent and the line + on which its children are arranged. When given to a single child, + this will set the distance for this child only. + +\begin{codeexample}[] +\begin{tikzpicture} + \node {root} + [level distance=20mm] + child + child { + [level distance=5mm] + child + child + child + } + child[level distance=10mm]; +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \tikzstyle{level 1}=[level distance=10mm] + \tikzstyle{level 2}=[level distance=5mm] + \node {root} + child + child { + child + child[level distance=10mm] + child + } + child; +\end{tikzpicture} +\end{codeexample} + + \itemoption{sibling distance}|=|\meta{distance} + This option specifies the distance between the anchors of the + children of a parent node. + +\begin{codeexample}[] +\begin{tikzpicture}[level distance=4mm] + \tikzstyle{level 1}=[sibling distance=8mm] + \tikzstyle{level 2}=[sibling distance=4mm] + \tikzstyle{level 3}=[sibling distance=2mm] + \coordinate + child { + child {child child} + child {child child} + } + child { + child {child child} + child {child child} + }; +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture}[level distance=10mm] + \tikzstyle{every node}=[fill=red!60,circle,inner sep=1pt] + \tikzstyle{level 1}=[sibling distance=20mm, + set style={{every node}+=[fill=red!45]}] + \tikzstyle{level 2}=[sibling distance=10mm, + set style={{every node}+=[fill=red!30]}] + \tikzstyle{level 3}=[sibling distance=5mm, + set style={{every node}+=[fill=red!15]}] + \node {31} + child {node {30} + child {node {20} + child {node {5}} + child {node {4}} + } + child {node {10} + child {node {9}} + child {node {1}} + } + } + child {node {20} + child {node {19} + child {node {1}} + child[fill=none] {edge from parent[draw=none]} + } + child {node {18}} + }; +\end{tikzpicture} +\end{codeexample} + + \itemoption{grow}|=|\meta{direction} + This option is used to define the \meta{direction} in which the tree + will grow. The \meta{direction} can either be an angle in degrees or + one of the following special text strings: |down|, |up|, |left|, + |right|, |north|, |south|, |east|, |west|, |north east|, + |north west|, |south east|, and |south west|. All of these have + ``their obvious meaning,'' so, say, |south west| is the same as the + angle $-135^\circ$. + + As a side effect, this option installs the default growth function. + + In addition to setting the direction, this option also has a + seemingly strange effect: It sets the sibling distance for the + current level to |0pt|, but leaves the sibling distance for later + levels unchanged. + + This somewhat strange behaviour has a highly desirable effect: If + you give this option before the list of children of a node starts, + the ``current level'' is still the parent level. Each child will be + on a later level and, hence, the sibling distance will be as + specified originally. This will cause the children to be neatly + aligned in a line orthogonal to the given \meta{direction}. However, + if you give this option locally to a single child, then ``current + level'' will be the same as the child's level. The zero sibling + distance will then cause the child to be placed exactly at a point + at distance |level distance| in the direction + \meta{direction}. However, the children of the child will be placed + ``normally'' on a line orthogonal to the \meta{direction}. + + These placement effects are best demonstrated by some examples: +\begin{codeexample}[] +\tikz \node {root} [grow=right] child child; +\end{codeexample} + +\begin{codeexample}[] +\tikz \node {root} [grow=south west] child child; +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture}[level distance=10mm,sibling distance=5mm] + \node {root} + [grow=down] + child + child + child[grow=right] { + child child child + }; +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture}[level distance=2em] + \node {C} + child[grow=up] {node {H}} + child[grow=left] {node {H}} + child[grow=down] {node {H}} + child[grow=right] {node {C} + child[grow=up] {node {H}} + child[grow=right] {node {H}} + child[grow=down] {node {H}} + edge from parent[double] + coordinate (wrong) + }; + \draw[<-,red] ([yshift=-2mm]wrong) -- +(0,-1) + node[below]{This is wrong!}; +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \node[rectangle,draw] (a) at (0,0) {start node}; + \node[rectangle,draw] (b) at (2,1) {end}; + + \draw (a) -- (b) + node[coordinate,midway] {} + child[grow=100,<-] {node[above] {the middle is here}}; +\end{tikzpicture} +\end{codeexample} + + \itemoption{grow'}|=|\meta{direction} + This option has the same effect as |grow|, only the children are + arranged in the opposite order. + \itemoption{growth function}|=|\meta{macro name} + This rather low-level option allows you to set a new growth + function. The \meta{macro name} must be the name of a macro without + parameters. This macro will be called for each child of a node. + + The effect of executing the macro should be the following: It should + transform the coordinate system in such a way that the origin + becomes the place where the current child should be anchored. When + the macro is called, the current coordinate system will be setup + such that the anchor of the parent node is in the origin. Thus, in + each call, the \meta{macro name} must essentially do a shift to the + child's origin. When the macro is called, the \TeX\ counter + |\tikznumberofchildren| will be set to the total number of children + of the parent node and the counter |\tikznumberofcurrentchild| will + be set to the number of the current child. + + The macro may, in addition to shifting the coordinate system, also + transform the coordinate system further. For example, it could be + rotated or scaled. + + Additional growth functions are defined in the library, see + Section~\ref{section-tree-library}. +\end{itemize} + + + +\subsection{Edges From the Parent Node} + +\label{section-edge-from-parent} + +Every child node is connected to its parent node via a special kind of +edge called the |edge from parent|. This edge is added to the +\meta{child path} when the following path operation is encountered: + +\begin{pathoperation}{edge from parent}{\opt{\oarg{options}}} + This path operation can only be used inside \meta{child paths} and + should be given at the end, possibly followed by node specifications + (we will come to that). If a \meta{child path} does not contain this + operation, it will be added at the end of the \meta{child path} + automatically. + + This operation has several effects. The most important is that it + inserts the current ``edge from parent path'' into the child + path. The edge from parent path can be set using the following + option: + \begin{itemize} + \itemoption{edge from parent path}|=|\meta{path} + This options allows you to set the edge from parent path to a new + path. The default for this path is the following: + \begin{codeexample}[code only] +(\tikzparentnode\tikzparentanchor) -- (\tikzchildnode\tikzchildanchor) + \end{codeexample} + The |\tikzparentnode| is a macro that will expand to the name of + the parent node. This works even when you have not assigned a name + to the parent node, in this case an internal name is automatically + generated. The |\tikzchildnode| is a macro that expands to the + name of the child node. The two |...anchor| macros are empty by + default. So, what is essentially inserted is just the path segment + |(\tikzparentnode) -- (\tikzchildnode)|; which is exactly an edge + from the parent to the child. + + You can modify this edge from parent path to achieve all sorts of + effects. For example, we could replace the straight line by a + curve as follows: +\begin{codeexample}[] +\begin{tikzpicture}[edge from parent path= + {(\tikzparentnode.south) .. controls +(0,-1) and +(0,1) + .. (\tikzchildnode.north)}] + \node {root} + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; +\end{tikzpicture} +\end{codeexample} + + Further useful edge from parent paths are defined in the tree + library, see Section~\ref{section-tree-library}. + + As said before, the anchors in the default edge from parent path + are empty. However, you can set them using the following options: + \begin{itemize} + \itemoption{child anchor}|=|\meta{anchor} + Specifies the anchor where the edge from parent meets the child + node by setting the macro |\tikzchildanchor| to + |.|\meta{anchor}. + + If you specify |border| as the \meta{anchor}, then the macro + |\tikzchildanchor| is set to the empty string. The effect of + this is that the edge from the parent will meet the child on the + border at an automatically calculated position. +\begin{codeexample}[] +\begin{tikzpicture} + \node {root} + [child anchor=north] + child {node {left} edge from parent[dashed]} + child {node {right} + child {node {child}} + child {node {child} edge from parent[draw=none]} + }; +\end{tikzpicture} +\end{codeexample} + \itemoption{parent anchor}|=|\meta{anchor} + This option works the same way as the |child anchor|, only for + the parent. + \end{itemize} + \end{itemize} + + Besides inserting the edge from parent path, the |edge from parent| + operation has another effect: The \meta{options} are inserted + directly before the edge from parent path and the following style is + also installed prior to inserting the path: + \begin{itemize} + \itemstyle{edge from parent} + This style is inserted right before the edge from parent path and + before the \meta{options} are inserted. By default, it just draws + the edge from parent, but you can use it to make the edge look + different. +\begin{codeexample}[] +\begin{tikzpicture} + \tikzstyle{edge from parent}=[draw,red,thick] + \node {root} + child {node {left} edge from parent[dashed]} + child {node {right} + child {node {child}} + child {node {child} edge from parent[draw=none]} + }; +\end{tikzpicture} +\end{codeexample} + \end{itemize} + + Note: The \meta{options} inserted before the edge from parent path + is added \emph{apply to the whole child path}. Thus, it is not + possible to, say, draw a circle in red as part of the child path and + then have an edge to parent in blue. However, as always, the child + node is a node and can be drawn in a totally different way. + + Finally, the |edge from parent| operation has one more effect: It + causes all nodes \emph{following} the operation to be placed on the + edge. This is the same effect as if you had added the |pos| option + to all these nodes, see also Section~\ref{section-pos-option}. + + As an example, consider the following code: +\begin{codeexample}[code only] +\node (root) {} child {node (child) {} edge to parent node {label}}; +\end{codeexample} + The |edge to parent| operation and the following |node| operation + will, together, have the same effect as if we had said: +\begin{codeexample}[code only] +(root) -- (child) node [pos=0.5] {label} +\end{codeexample} + + Here is a more complicated example: +\begin{codeexample}[] +\begin{tikzpicture} + \node {root} + child { + node {left} + edge from parent + node[left] {a} + node[right] {b} + } + child { + node {right} + child { + node {child} + edge from parent + node[left] {c} + } + child {node {child}} + edge from parent + node[near end] {x} + }; +\end{tikzpicture} +\end{codeexample} + +\end{pathoperation} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial.tex new file mode 100644 index 00000000000..f0523e2aa97 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial.tex @@ -0,0 +1,1417 @@ +\section{Tutorial: A Picture for Karl's Students} + +This tutorial is intended for new users of \pgfname\ and \tikzname. It +does not give an exhaustive account of all the features of \tikzname\ or +\pgfname, just of those that you are likely to use right away. + +Karl is a math and chemistry high-school teacher. He used to create +the graphics in his worksheets and exams using \LaTeX's |{picture}| +environment. While the results were acceptable, creating the graphics +often turned out to be a lengthy process. Also, there tended to be +problems with lines having slightly wrong angles and circles also +seemed to be hard to get right. Naturally, his students could not care +less whether the lines had the exact right angles and they find +Karl's exams too difficult no matter how nicely they were drawn. But +Karl was never entirely satisfied with the result. + +Karl's son, who was even less satisfied with the results (he did not +have to take the exams, after all), told Karl that he might wish +to try out a new package for creating graphics. A bit confusingly, +this package seems to have two names: First, Karl had to download and +install a package called \pgfname. Then it turns out that inside this +package there is another package called \tikzname, which is supposed to +stand for ``\tikzname\ ist \emph{kein} Zeichenprogramm.'' Karl finds this +all a bit strange and \tikzname\ seems to indicate that the package +does not do what he needs. However, having used \textsc{gnu} +software for quite some time and ``\textsc{gnu} not being Unix,'' +there seems to be hope yet. His son assures him that \tikzname's name is +intended to warn people that \tikzname\ is not a program that you can +use to draw graphics with your mouse or tablet. Rather, it is more +like a ``graphics language.'' + + +\subsection{Problem Statement} + +Karl wants to put a graphic on the next worksheet for his +students. He is currently teaching his students about sine and +cosine. What he would like to have is something that looks like this +(ideally): + +\noindent +\begin{tikzpicture}[scale=3,cap=round] + % Local definitions + \def\costhirty{0.8660256} + + % Colors + \colorlet{anglecolor}{green!50!black} + \colorlet{sincolor}{red} + \colorlet{tancolor}{orange!80!black} + \colorlet{coscolor}{blue} + + % Styles + \tikzstyle axes=[] + \tikzstyle important line=[very thick] + \tikzstyle information text=[rounded corners,fill=red!10,inner sep=1ex] + + % The graphic + \draw[style=help lines,step=0.5cm] (-1.4,-1.4) grid (1.4,1.4); + + \draw (0,0) circle (1cm); + + \begin{scope}[style=axes] + \draw[->] (-1.5,0) -- (1.5,0) node[right] {$x$}; + \draw[->] (0,-1.5) -- (0,1.5) node[above] {$y$}; + + \foreach \x/\xtext in {-1, -.5/-\frac{1}{2}, 1} + \draw[xshift=\x cm] (0pt,1pt) -- (0pt,-1pt) node[below,fill=white] {$\xtext$}; + + \foreach \y/\ytext in {-1, -.5/-\frac{1}{2}, .5/\frac{1}{2}, 1} + \draw[yshift=\y cm] (1pt,0pt) -- (-1pt,0pt) node[left,fill=white] {$\ytext$}; + \end{scope} + + \filldraw[fill=green!20,draw=anglecolor] (0,0) -- (3mm,0pt) arc(0:30:3mm); + \draw (15:2mm) node[anglecolor] {$\alpha$}; + + \draw[style=important line,sincolor] + (30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} +(0,-.5); + + \draw[style=important line,coscolor] + (0,0) -- node[below=2pt,fill=white] {$\cos \alpha$} (\costhirty,0); + + \draw[style=important line,tancolor] (1,0) -- + node [right=1pt,fill=white] + { + $\displaystyle \tan \alpha \color{black}= + \frac{{\color{sincolor}\sin \alpha}}{\color{coscolor}\cos \alpha}$ + } (intersection of 0,0--30:1cm and 1,0--1,1) coordinate (t); + + \draw (0,0) -- (t); + + \draw[xshift=1.85cm] node [right,text width=6cm,style=information text] + { + The {\color{anglecolor} angle $\alpha$} is $30^\circ$ in the + example ($\pi/6$ in radians). The {\color{sincolor}sine of + $\alpha$}, which is the height of the red line, is + \[ + {\color{sincolor} \sin \alpha} = 1/2. + \] + By the Theorem of Pythagoras we have ${\color{coscolor}\cos^2 \alpha} + + {\color{sincolor}\sin^2\alpha} =1$. Thus the length of the blue + line, which is the {\color{coscolor}cosine of $\alpha$}, must be + \[ + {\color{coscolor}\cos\alpha} = \sqrt{1 - 1/4} = \textstyle + \frac{1}{2} \sqrt 3. + \]% + This shows that {\color{tancolor}$\tan \alpha$}, which is the + height of the orange line, is + \[ + {\color{tancolor}\tan\alpha} = \frac{{\color{sincolor}\sin + \alpha}}{\color{coscolor}\cos \alpha} = 1/\sqrt 3. + \]% + }; +\end{tikzpicture} + + +\subsection{Setting up the Environment} + +In \tikzname, to draw a picture, at the start of the picture +you need to tell \TeX\ or \LaTeX\ that you want to start a picture. In +\LaTeX\ this is done using the environment |{tikzpicture}|, in plain +\TeX\ you just use |\tikzpicture| to start the picture and +|\endtikzpicture| to end it. + +\subsubsection{Setting up the Environment in \LaTeX} + +Karl, being a \LaTeX\ user, thus sets up his file as follows: + +\begin{codeexample}[code only] +\documentclass{article} % say +\usepackage{tikz} +\begin{document} +We are working on +\begin{tikzpicture} + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); +\end{tikzpicture}. +\end{document} +\end{codeexample} + +When executed, that is, run via |pdflatex| or via |latex| followed by +|dvips|, the resulting will contain something that looks like this: + +\begin{codeexample}[width=7cm] +We are working on +\begin{tikzpicture} + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); +\end{tikzpicture}. +\end{codeexample} + +Admittedly, not quite the whole picture, yet, but we +do have the axes established. Well, not quite, but we have the lines +that make up the axes drawn. Karl suddenly has a sinking feeling +that the picture is still some way off. + +Let's have a more detailed look at the code. First, the package +|tikz| is loaded. This package is a so-called ``frontend'' to the +basic \pgfname\ system. The basic layer, which is also described in this +manual, is somewhat more, well, basic and thus harder to use. The +frontend makes things easier by providing a simpler syntax. + +Inside the environment there are two |\draw| commands. They mean: +``The path, which is specified following the command up to the +semicolon, should be drawn.'' The first path is specified +as |(-1.5,0) -- (0,1.5)|, which means ``a straight line from the point +at position $(-1.5,0)$ to the point at position $(0,1.5)$.'' Here, the +positions are specified within a special coordinate system in which, +initially, one unit is 1cm. + +Karl is quite pleased to note that the environment automatically +reserves enough space to encompass the picture. + + +\subsubsection{Setting up the Environment in Plain \TeX} + +Karl's wife Gerda, who also happens to be a math teacher, is not a +\LaTeX\ user, but uses plain \TeX\ since she prefers to do things +``the old way.'' She can also use \tikzname. Instead of +|\usepackage{tikz}| she has to write |\input tikz.tex| and instead of +|\begin{tikzpicture}| she writes |\tikzpicture| and instead of + |\end{tikzpicture}| she writes |\endtikzpicture|. + +Thus, she would use: +\begin{codeexample}[code only] +%% Plain TeX file +\input tikz.tex +\baselineskip=12pt +\hsize=6.3truein +\vsize=8.7truein +We are working on +\tikzpicture + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); +\endtikzpicture. +\bye +\end{codeexample} + +Gerda can typeset this file using either |pdftex| or |tex| together +with |dvips|. \tikzname\ will automatically discern which driver she is +using. If she wishes to use |dvipdfm| together with |tex|, she +either needs to modify the file |pgf.cfg| or can write +|\def\pgfsysdriver{pgfsys-dvipdfm.def}| somewhere \emph{before} she +inputs |tikz.tex| or |pgf.tex|. + + + + +\subsection{Straight Path Construction} + +The basic building block of all pictures in \tikzname\ is the path. +A \emph{path} is a series of straight lines and curves that are +connected (that is not the whole picture, but let us ignore the +complications for the moment). You start a path by specifying the +coordinates of the start position as a point in round brackets, as in +|(0,0)|. This is followed by a series of ``path extension +operations.'' The simplest is |--|, which we used already. It must be +followed by another coordinate and it extends the path in a straight +line to this new position. For example, if we were to turn the two +paths of the axes into one path, the following would result: + +\begin{codeexample}[] +\tikz \draw (-1.5,0) -- (1.5,0) -- (0,-1.5) -- (0,1.5); +\end{codeexample} + +Karl is a bit confused by the fact that there is no |{tikzpicture}| +environment, here. Instead, the little command |\tikz| is used. This +command either takes one argument (starting with an opening brace as in +|\tikz{\draw (0,0) -- (1.5,0)}|, which yields \tikz{\draw (0,0) + --(1.5,0);}) or collects everything up to the next semicolon and +puts it inside a |{tikzpicture}| environment. As a rule of thumb, all +\tikzname\ graphic drawing commands must occur as an argument of |\tikz| +or inside a |{tikzpicture}| environment. Fortunately, the command +|\draw| will only be defined inside this environment, so there is +little chance that you will accidentally do something wrong here. + + + +\subsection{Curved Path Construction} + +The next thing Karl wants to do is to draw the circle. For this, +straight lines obviously will not do. Instead, we need some way to +draw curves. For this, \tikzname\ provides a special syntax. One or two +``control points'' are needed. The math behind them is not quite +trivial, but here is the basic idea: Suppose you are at point $x$ and +the first control point is $y$. Then the curve will start ``going in +the direction of~$y$ at~$x$,'' that is, the tangent of the curve at $x$ +will point toward~$y$. Next, suppose the curve should end at $z$ and +the second support point is $w$. Then the curve will, indeed, end at +$z$ and the tangent of the curve at point $z$ will go through $w$. + +Here is an example (the control points have been added for clarity): +\begin{codeexample}[] +\begin{tikzpicture} + \filldraw [gray] (0,0) circle (2pt) + (1,1) circle (2pt) + (2,1) circle (2pt) + (2,0) circle (2pt); + \draw (0,0) .. controls (1,1) and (2,1) .. (2,0); +\end{tikzpicture} +\end{codeexample} + +The general syntax for extending a path in a ``curved'' way is +|.. controls| \meta{first control point} |and| \meta{second control + point} |..| \meta{end point}. You can leave out the |and| +\meta{second control point}, which causes the first one to be used +twice. + +So, Karl can now add the first half circle to the picture: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (-1,0) .. controls (-1,0.555) and (-0.555,1) .. (0,1) + .. controls (0.555,1) and (1,0.555) .. (1,0); +\end{tikzpicture} +\end{codeexample} + +Karl is happy with the result, but finds specifying circles in this +way to be extremely awkward. Fortunately, there is a much simpler way. + + +\subsection{Circle Path Construction} + +In order to draw a circle, the path construction operation |circle| can +be used. This operation is followed by a radius in round brackets as in +the following example: (Note that the previous position is used as the +\emph{center} of the circle.) + +\begin{codeexample}[] +\tikz \draw (0,0) circle (10pt); +\end{codeexample} + +You can also append an ellipse to the path using the |ellipse| +operation. Instead of a single radius you can specify two of them, one +for the $x$-direction and one for the $y$-direction, separated by +|and|: + +\begin{codeexample}[] +\tikz \draw (0,0) ellipse (20pt and 10pt); +\end{codeexample} + +To draw an ellipse whose axes are not horizontal and vertical, but +point in an arbitrary direction (a ``turned ellipse'' like \tikz +\draw[rotate=30] (0,0) ellipse (6pt and 3pt);) you can use +transformations, which are explained later. The code for the little +ellipse is |\tikz \draw[rotate=30] (0,0) ellipse (6pt and 3pt);|, by +the way. + +So, returning to Karl's problem, he can write +|\draw (0,0) circle (1cm);| to draw the circle: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); +\end{tikzpicture} +\end{codeexample} + + +At this point, Karl is a bit alarmed that the circle is so small when +he wants the final picture to be much bigger. He is pleased to learn +that \tikzname\ has powerful transformation options and scaling +everything by a factor of three is very easy. But let us leave the +size as it is for the moment to save some space. + + + + +\subsection{Rectangle Path Construction} + +The next things we would like to have is the grid in the background. +There are several ways to produce it. For example, one might draw lots of +rectangles. Since rectangles are so common, there is a special syntax +for them: To add a rectangle to the current path, use the |rectangle| +path construction operation. This operation should be followed by another +coordinate and will append a rectangle to the path such that the +previous coordinate and the next coordinates are corners of the +rectangle. So, let us add two rectangles to the picture: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \draw (0,0) rectangle (0.5,0.5); + \draw (-0.5,-0.5) rectangle (-1,-1); +\end{tikzpicture} +\end{codeexample} + +While this may be nice in other situations, this is not really leading +anywhere with Karl's problem: First, we would need an awful lot of +these rectangles and then there is the border that is not ``closed.'' + +So, Karl is about to resort to simply drawing four vertical and four +horizontal lines using the nice |\draw| command, when he learns that +there is a |grid| path construction operation. + + + +\subsection{Grid Path Construction} + +The |grid| path operation adds a grid to the current path. It will add +lines making up a grid that fills the rectangle whose one corner is +the current point and whose other corner is the point following the +|grid| operation. For example, the code +|\tikz \draw[step=2pt] (0,0) grid (10pt,10pt);| produces \tikz +\draw[step=2pt] (0,0) grid (10pt,10pt);. Note how the optional +argument for |\draw| can be used to specify a grid width (there are +also |xstep| and |ystep| to define the steppings independently). As +Karl will learn soon, there are \emph{lots} of things that can be +influenced using such options. + +For Karl, the following code could be used: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \draw[step=.5cm] (-1.4,-1.4) grid (1.4,1.4); +\end{tikzpicture} +\end{codeexample} + +Having another look at the desired picture, Karl notices that it would +be nice for the grid to be more subdued. (His son told him that grids +tend to be distracting if they are not subdued.) To subdue the grid, +Karl adds two more options to the |\draw| command that draws the +grid. First, he uses the color |gray| for the grid lines. Second, he +reduces the line width to |very thin|. Finally, he swaps the ordering +of the commands so that the grid is drawn first and everything else on +top. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); +\end{tikzpicture} +\end{codeexample} + + +\subsection{Adding a Touch of Style} + +Instead of the options |gray,very thin| Karl could also have +said |style=help lines|. \emph{Styles} are predefined sets of options +that can be used to organize how a graphic is drawn. By saying +|style=help lines| you say ``use the style that I (or someone else) +has set for drawing help lines.'' If Karl decides, at some later +point, that grids should be drawn, say, using the color |blue!50| +instead of |gray|, he could say the following: +\begin{codeexample}[code only] +\tikzstyle help lines=[color=blue!50,very thin] +\end{codeexample} +Alternatively, he could have said the following: +\begin{codeexample}[code only] +\tikzstyle help lines+=[color=blue!50] +\end{codeexample} +This would have added the |color=blue!50| option. The |help lines| +style would now contain \emph{two} color options, but +the second would override the first. + +Using styles makes your graphics code more flexible. You can +change the way things look easily in a consistent manner. + +To build a hierarchy of styles you can have one style use +another. So in order to define a style |Karl's grid| that is based on +the |grid| style Karl could say +\begin{codeexample}[code only] +\tikzstyle Karl's grid=[style=help lines,color=blue!50] +... +\draw[style=Karl's grid] (0,0) grid (5,5); +\end{codeexample} + +You can also leave out the |style=|. Thus, whenever \tikzname\ encounters +an options that it does not know about, it will check whether this +option happens to be the name of a style. If so, the style is +used. Thus, Karl could also have written: +\begin{codeexample}[code only] +\tikzstyle Karl's grid=[help lines,color=blue!50] +... +\draw[Karl's grid] (0,0) grid (5,5); +\end{codeexample} + +For some styles, like the |very thin| style, it is pretty clear what +the style does and there is no need to say |style=very thin|. For +other styles, like |help lines|, it seems more natural to me to say +|style=help lines|. But, mainly, this is a matter of taste. + + +\subsection{Drawing Options} + +Karl wonders what other options there are that influence how a path is +drawn. He saw already that the |color=|\meta{color} option can be used +to set the line's color. The option |draw=|\meta{color} does nearly +the same, only it sets the color for the lines only and a different +color can be used for filling (Karl will need this when he fills the +arc for the angle). + +He saw that the style |very thin| yields very thin lines. Karl is not +really surprised by this and neither is he surprised to learn that |thin| +yields thin lines, |thick| yields thick lines, |very thick| yields +very thick lines, |ultra thick| yields really, really thick lines and +|ultra thin| yields lines that are so thin that low-resolution printers +and displays will have trouble showing them. He wonders what gives +lines of ``normal'' thickness. It turns out that |thin| is the correct +choice. This seems strange to Karl, but his son explains him that +\LaTeX\ has two commands called |\thinlines| and |\thicklines| and +that |\thinlines| gives the line width of ``normal'' lines, more +precisely, of the thickness that, say, the stem of a letter like ``T'' +or ``i'' has. Nevertheless, Karl would like to know whether there is +anything ``in the middle'' between |thin| and |thick|. There is: +|semithick|. + +Another useful thing one can do with lines is to dash or dot them. For +this, the two styles |dashed| and |dotted| can be used, yielding +\tikz \draw[dashed] (0,0) -- (10pt,0pt); and \tikz \draw[dotted] (0,0) +-- (10pt,0pt);. Both options also exist in a loose and a dense +version, called |loosely dashed|, |densely dashed|, |loosely dotted|, +and |closely dotted|. If he really, really needs to, Karl can also +define much more complex dashing patterns with the |dash pattern| +option, but his son insists that dashing is to be used with utmost +care and mostly distracts. Karl's son claims that complicated dashing +patterns are evil. Karl's students do not care about dashing patterns. + + + +\subsection{Arc Path Construction} + +Our next obstacle is to draw the arc for the angle. For this, the +|arc| path construction operation is useful, which draws part of a +circle or ellipse. This |arc| operation must be followed by a triple in +rounded brackets, where the components of the triple are separated by +colons. The first two components are angles, the last one is a +radius. An example would be |(10:80:10pt)|, which means ``an arc from +10 degrees to 80 degrees on a circle of radius 10pt.'' Karl obviously +needs an arc from $0^\circ$ to $30^\circ$. The radius should be +something relatively small, perhaps around one third of the circle's +radius. This gives: |(0:30:3mm)|. + +When one uses the arc path construction operation, the specified arc will +be added with its starting point at the current position. So, we first +have to ``get there.'' + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \draw (3mm,0mm) arc (0:30:3mm); +\end{tikzpicture} +\end{codeexample} + +Karl thinks this is really a bit small and he cannot continue unless +he learns how to do scaling. For this, he can add the |[scale=3]| +option. He could add this option to each |\draw| command, but that +would be awkward. Instead, he adds it to the whole environment, which +causes this option to apply to everything within. + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \draw (3mm,0mm) arc (0:30:3mm); +\end{tikzpicture} +\end{codeexample} + +As for circles, you can specify ``two'' radii in order to get an +elliptical arc. + +\begin{codeexample}[] + \tikz \draw (0,0) arc (0:315:1.75cm and 1cm); +\end{codeexample} + + +\subsection{Clipping a Path} + +In order to save space in this manual, it would be nice to clip Karl's +graphics a bit so that we can focus on the ``interesting'' +parts. Clipping is pretty easy in \tikzname. You can use the |\clip| +command clip all subsequent drawing. It works like |\draw|, only it +does not draw anything, but uses the given path to clip everything +subsequently. + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip (-0.1,-0.2) rectangle (1.1,0.75); + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \draw (3mm,0mm) arc (0:30:3mm); +\end{tikzpicture} +\end{codeexample} + +You can also do both at the same time: Draw \emph{and} clip a +path. For this, use the |\draw| command and add the |clip| +option. (This is not the whole picture: You can also use the |\clip| +command and add the |draw| option. Well, that is also not the whole +picture: In reality, |\draw| is just a shorthand for |\path[draw]| +and |\clip| is a shorthand for |\path[clip]| and you could also say +|\path[draw,clip]|.) Here is an example: + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip[draw] (0.5,0.5) circle (.6cm); + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \draw (3mm,0mm) arc (0:30:3mm); +\end{tikzpicture} +\end{codeexample} + + +\subsection{Parabola and Sine Path Construction} + +Although Karl does not need them for his picture, he is pleased to +learn that there are |parabola| and |sin| and |cos| path operations for +adding parabolas and sine and cosine curves to the current path. For the +|parabola| operation, the current point will lie on the parabola as +well as the point given after the parabola operation. Consider +the following example: + +\begin{codeexample}[] +\tikz \draw (0,0) rectangle (1,1) (0,0) parabola (1,1); +\end{codeexample} + +It is also possible to place the bend somewhere else: + +\begin{codeexample}[] +\tikz \draw[x=1pt,y=1pt] (0,0) parabola bend (4,16) (6,12); +\end{codeexample} + +The operations |sin| and |cos| add a sine or cosine curve in the interval +$[0,\pi/2]$ such that the previous current point is at the start of +the curve and the curve ends at the given end point. Here are two +examples: +\begin{codeexample}[] +A sine \tikz \draw[x=1ex,y=1ex] (0,0) sin (1.57,1); curve. +\end{codeexample} + +\begin{codeexample}[] +\tikz \draw[x=1.57ex,y=1ex] (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0) + (0,1) cos (1,0) sin (2,-1) cos (3,0) sin (4,1); +\end{codeexample} + + + +\subsection{Filling and Drawing} + +Returning to the picture, Karl now wants the angle to be ``filled'' +with a very light green. For this he uses |\fill| instead of +|\draw|. Here is what Karl does: + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip (-0.1,-0.2) rectangle (1.1,0.75); + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \fill[green!20!white] (0,0) -- (3mm,0mm) arc (0:30:3mm) -- (0,0); +\end{tikzpicture} +\end{codeexample} + +The color |green!20!white| means 20\% green and 80\% white mixed +together. Such color expression are possible since \pgfname\ uses Uwe +Kern's |xcolor| package, see the documentation of that package for +details on color expressions. + +What would have happened, if Karl had not ``closed'' the path using +|--(0,0)| at the end? In this case, the path is closed automatically, +so this could have been omitted. Indeed, it would even have been +better to write the following, instead: +\begin{codeexample}[code only] + \fill[green!20!white] (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; +\end{codeexample} +The |--cycle| causes the current path to be closed (actually the +current part of the current path) by smoothly joining the first and +last point. To appreciate the difference, consider the following +example: + +\begin{codeexample}[] +\begin{tikzpicture}[line width=5pt] + \draw (0,0) -- (1,0) -- (1,1) -- (0,0); + \draw (2,0) -- (3,0) -- (3,1) -- cycle; + \useasboundingbox (0,1.5); % make bounding box higher +\end{tikzpicture} +\end{codeexample} + +You can also fill and draw a path at the same time using the +|\filldraw| command. This will first draw the path, then fill it. This +may not seem too useful, but you can specify different colors to be +used for filling and for stroking. These are specified as optional +arguments like this: + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip (-0.1,-0.2) rectangle (1.1,0.75); + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \filldraw[fill=green!20!white, draw=green!50!black] + (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; +\end{tikzpicture} +\end{codeexample} + + + +\subsection{Shading} + +Karl briefly considers the possibility of making the angle ``more +fancy'' by \emph{shading} it. Instead of filling the with a uniform +color, a smooth transition between different colors is used. For this, +|\shade| and |\shadedraw|, for shading and drawing at the same time, +can be used: + +\begin{codeexample}[] + \tikz \shade (0,0) rectangle (2,1) (3,0.5) circle (.5cm); +\end{codeexample} +The default shading is a smooth transition from gray to white. To +specify different colors, you can use options: + +\begin{codeexample}[] +\begin{tikzpicture}[rounded corners,ultra thick] + \shade[top color=yellow,bottom color=black] (0,0) rectangle +(2,1); + \shade[left color=yellow,right color=black] (3,0) rectangle +(2,1); + \shadedraw[inner color=yellow,outer color=black,draw=yellow] (6,0) rectangle +(2,1); + \shade[ball color=green] (9,.5) circle (.5cm); +\end{tikzpicture} +\end{codeexample} + +For Karl, the following might be appropriate: + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip (-0.1,-0.2) rectangle (1.1,0.75); + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \shadedraw[left color=gray,right color=green, draw=green!50!black] + (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; +\end{tikzpicture} +\end{codeexample} + +However, he wisely decides that shadings usually only distract without +adding anything to the picture. + + +\subsection{Specifying Coordinates} + +Karl now wants to add the sine and cosine lines. He knows already that +he can use the |color=| option to set the lines's colors. So, what is +the best way to specify the coordinates? + +There are different ways of specifying coordinates. The easiest way is +to say something like |(10pt,2cm)|. This means 10pt in $x$-direction +and 2cm in $y$-directions. Alternatively, you can also leave out the +units as in |(1,2)|, which means ``one times the current $x$-vector +plus twice the current $y$-vector.'' These vectors default to 1cm in +the $x$-direction and 1cm in the $y$-direction, respectively. + +In order to specify points in polar coordinates, use the notation +|(30:1cm)|, which means 1cm in direction 30 degree. This is obviously +quite useful to ``get to the point $(\cos 30^\circ,\sin 30^\circ)$ on +the circle.'' + +You can add a single |+| sign in front of a coordinate or two of +them as in |+(1cm,0cm)| or |++(0cm,2cm)|. Such coordinates are interpreted +differently: The first form means ``1cm upwards from the previous +specified position'' and the second means ``2cm to the right of the +previous specified position, making this the new specified position.'' +For example, we can draw the sine line as follows: + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip (-0.1,-0.2) rectangle (1.1,0.75); + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \filldraw[fill=green!20,draw=green!50!black] + (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; + \draw[red,very thick] (30:1cm) -- +(0,-0.5); +\end{tikzpicture} +\end{codeexample} + +Karl used the fact $\sin 30^\circ = 1/2$. However, he very much +doubts that his students know this, so it would be nice to have a way +of specifying ``the point straight down from |(30:1cm)| that lies on +the $x$-axis.'' This is, indeed, possible using a special syntax: Karl +can write \verb!(30:1cm |- 0,0)!. In general, the meaning of +|(|\meta{p}\verb! |- !\meta{q}|)| is ``the intersection of a vertical +line through $p$ and a horizontal line through $q$.'' + +Next, let us draw the cosine line. One way would be to say +\verb!(30:1cm |- 0,0) -- (0,0)!. Another way is the following: we +``continue'' from where the sine ends: + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip (-0.1,-0.2) rectangle (1.1,0.75); + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \draw (-1.5,0) -- (1.5,0); + \draw (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc + (0:30:3mm) -- cycle; + \draw[red,very thick] (30:1cm) -- +(0,-0.5); + \draw[blue,very thick] (30:1cm) ++(0,-0.5) -- (0,0); +\end{tikzpicture} +\end{codeexample} + +Note the there is no |--| between |(30:1cm)| and |+(0,-0.5)|. In +detail, this path is interpreted as follows: ``First, the |(30:1cm)| +tells me to move by pen to $(\cos 30^\circ,1/2)$. Next, there comes +another coordinate specification, so I move my pen there without drawing +anything. This new point is half a unit down from the last position, +thus it is at $(\cos 30^\circ,0)$. Finally, I move the pen to the +origin, but this time drawing something (because of the |--|).'' + +To appreciate the difference between |+| and |++| consider the +following example: + +\begin{codeexample}[] +\begin{tikzpicture} + \def\rectanglepath{-- ++(1cm,0cm) -- ++(0cm,1cm) -- ++(-1cm,0cm) -- cycle} + \draw (0,0) \rectanglepath; + \draw (1.5,0) \rectanglepath; +\end{tikzpicture} +\end{codeexample} + +By comparison, when using a single |+|, the coordinates are different: + +\begin{codeexample}[] +\begin{tikzpicture} + \def\rectanglepath{-- +(1cm,0cm) -- +(1cm,1cm) -- +(0cm,1cm) -- cycle} + \draw (0,0) \rectanglepath; + \draw (1.5,0) \rectanglepath; +\end{tikzpicture} +\end{codeexample} + + +Naturally, all of this could have been written more clearly and more +economically like this (either with a single of a double |+|): +\begin{codeexample}[] +\tikz \draw (0,0) rectangle +(1,1) (1.5,0) rectangle +(1,1); +\end{codeexample} + + + +Karl is left with the line for $\tan \alpha$, which seems difficult to +specify using transformations and polar coordinates. For this he needs +another way of specifying coordinates: Karl can specify intersections +of lines as coordinates. The line for $\tan \alpha$ starts at $(1,0)$ +and goes upward to a point that is at the intersection of a line going +``up'' and a line going from the origin through |(30:1cm)|. The syntax +for this point is the following: + +\begin{codeexample}[code only] +\draw[very thick,orange] (1,0) -- (intersection of 1,0--1,1 and 0,0--30:1cm); +\end{codeexample} + +In the following, two final examples of how to use relative +positioning are presented. Note that the transformation options, +which are explained later, are often more useful for shifting than +relative positioning. + +\begin{codeexample}[] +\begin{tikzpicture}[scale=0.5] + \draw (0,0) -- (90:1cm) arc (90:360:1cm) arc (0:30:1cm) -- cycle; + \draw (60:5pt) -- +(30:1cm) arc (30:90:1cm) -- cycle; + + \draw (3,0) +(0:1cm) -- +(72:1cm) -- +(144:1cm) -- +(216:1cm) -- + +(288:1cm) -- cycle; +\end{tikzpicture} +\end{codeexample} + + + +\subsection{Adding Arrow Tips} + +Karl now wants to add the little arrow tips at the end of the axes. He has +noticed that in many plots, even in scientific journals, these arrow tips +seem to missing, presumably because the generating programs cannot +produce them. Karl thinks arrow tips belong at the end of axes. His +son agrees. His students do not care about arrow tips. + +It turns out that adding arrow tips is pretty easy: Karl adds the option +|->| to the drawing commands for the axes: + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip (-0.1,-0.2) rectangle (1.1,1.51); + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \draw[->] (-1.5,0) -- (1.5,0); + \draw[->] (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc + (0:30:3mm) -- cycle; + \draw[red,very thick] (30:1cm) -- +(0,-0.5); + \draw[blue,very thick] (30:1cm) ++(0,-0.5) -- (0,0); + \draw[orange,very thick] (1,0) -- (intersection of 1,0--1,1 and 0,0--30:1cm); +\end{tikzpicture} +\end{codeexample} + +If Karl had used the option |<-| instead of |->|, arrow tips would +have been put at the beginning of the path. The option |<->| puts +arrow tips at both ends of the path. + +There are certain restrictions to the kind of paths to which arrow tips +can be added. As a rule of thumb, you can add arrow tips only to a +single open ``line.'' For example, you should not try to add tips to, +say, a rectangle or a circle. (You can try, but no guarantees as to what +will happen now or in future versions.) However, you can add arrow +tips to curved paths and to paths that have several segments, as in +the following examples: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw [<->] (0,0) arc (180:30:10pt); + \draw [<->] (1,0) -- (1.5cm,10pt) -- (2cm,0pt) -- (2.5cm,10pt); +\end{tikzpicture} +\end{codeexample} + +Karl has a more detailed look at the arrow that \tikzname\ puts at the +end. It looks like this when he zooms it: \tikz { \useasboundingbox + (0pt,-.5ex) rectangle (10pt,.5ex); \draw[->,line width=1pt] (0pt,0pt) -- + (10pt,0pt); }. The shape seems vaguely familiar and, indeed, this is +exactly the end of \TeX's standard arrow used in something like +$f\colon A \to B$. + + +Karl likes the arrow, especially since it is not ``as thick'' as the +arrows offered by many other packages. However, he expects that, +sometimes, he might need to use some other kinds of arrow. +To do so, Karl can say |>=|\meta{right arrow tip kind}, where +\meta{right arrow tip kind} is a special arrow tip specification. For +example, if Karl says |>=stealth|, then he tells \tikzname\ +that he would like ``stealth-fighter-like'' arrow tips: + +\begin{codeexample}[] +\begin{tikzpicture}[>=stealth] + \draw [->] (0,0) arc (180:30:10pt); + \draw [<<-,very thick] (1,0) -- (1.5cm,10pt) -- (2cm,0pt) -- (2.5cm,10pt); +\end{tikzpicture} +\end{codeexample}%>> + +Karl wonders whether such a military name for the arrow type is really +necessary. He is not really mollified when his son tells him that +Microsoft's PowerPoint uses the same name. He decides to have his +students discuss this at some point. + +In addition to |stealth| there are several other predefined arrow tip +kinds Karl can choose from, see +Section~\ref{section-library-arrows}. Furthermore, he can define +arrows types himself, if he needs new ones. + + + + +\subsection{Scoping} + +Karl saw already that there are numerous graphic options that affect how +paths are rendered. Often, he would like to apply certain options to +a whole set of graphic commands. For example, Karl might wish to draw +three paths using a |thick| pen, but would like everything else to +be drawn ``normally.'' + +If Karl wishes to set a certain graphic option for the whole picture, +he can simply pass this option to the |\tikz| command or to the +|{tikzpicture}| environment (Gerda would pass the options to +|\tikzpicture|). However, if Karl wants to apply graphic options to a +local group, he put these commands inside a |{scope}| environment +(Gerda uses |\scope| and |\endscope|). This environment takes graphic +options as an optional argument and these options apply to everything +inside the scope, but not to anything outside. + +Here is an example: + +\begin{codeexample}[] +\begin{tikzpicture}[ultra thick] + \draw (0,0) -- (0,1); + \begin{scope}[thin] + \draw (1,0) -- (1,1); + \draw (2,0) -- (2,1); + \end{scope} + \draw (3,0) -- (3,1); +\end{tikzpicture} +\end{codeexample} + +Scoping has another interesting effect: Any changes to the clipping +area are local to the scope. Thus, if you say |\clip| somewhere inside +a scope, the effect of the |\clip| command ends at the end of the +scope. This is useful since there is no other way of ``enlarging'' the +clipping area. + +Karl has also already seen that giving options to commands like +|\draw| apply only to that command. In turns out that the situation is +slightly more complex. First, options to a command like |\draw| are +not really options to the command, but they are ``path options'' and +can be given anywhere on the path. So, instead of +|\draw[thin] (0,0) -- (1,0);| one can also write +|\draw (0,0) [thin] -- (1,0);| or |\draw (0,0) -- (1,0) [thin];|; all +of these have the same effect. This might seem strange since in the +last case, it would appear that the |thin| should take effect only +``after'' the line from $(0,0)$ to $(1,0)$ has been draw. However, +most graphic options only apply to the whole path. Indeed, if you say +both |thin| and |thick| on the same path, the last option given will +``win.'' + +When reading the above, Karl notices that only ``most'' graphic +options apply to the whole path. Indeed, all transformation options do +\emph{not} apply to the whole path, but only to ``everything following +them on the path.'' We will have a more detailed look at this in a +moment. Nevertheless, all options given during a path construction +apply only to this path. + + + +\subsection{Transformations} + +When you specify a coordinate like |(1cm,1cm)|, where is that +coordinate placed on the page? To determine the position, \tikzname, +\TeX, and \textsc{pdf} or PostScript all apply certain transformations +to the given coordinate in order to determine the finally position on +the page. + +\tikzname\ provides numerous options that allow you to transform +coordinates in \pgfname's private coordinate system. For example, the +|xshift| option allows you to shift all subsequent points by a certain +amount: + +\begin{codeexample}[] +\tikz \draw (0,0) -- (0,0.5) [xshift=2pt] (0,0) -- (0,0.5); +\end{codeexample} + +It is important to note that you can change transformation ``in the +middle of a path,'' a feature that is not supported by \pdf\ +or PostScript. The reason is that \pgfname\ keeps track of its own +transformation matrix. + +Here is a more complicated example: +\begin{codeexample}[] +\begin{tikzpicture}[even odd rule,rounded corners=2pt,x=10pt,y=10pt] + \filldraw[fill=examplefill] (0,0) rectangle (1,1) + [xshift=5pt,yshift=5pt] (0,0) rectangle (1,1) + [rotate=30] (-1,-1) rectangle (2,2); +\end{tikzpicture} +\end{codeexample} + +The most useful transformations are |xshift| and |yshift| for +shifting, |shift| for shifting to a given point as in |shift={(1,0)}| +or |shift={+(0,0)}| (the braces are necessary so that \TeX\ does not +mistake the comma for separating options), |rotate| for rotating by a +certain angle (there is also a |rotate around| for rotating around a +given point), |scale| for scaling by a certain factor, |xscale| and +|yscale| for scaling only in the $x$- or $y$-direction (|xscale=-1| is +a flip), and |xslant| and |yslant| for slanting. If these +transformation and those that I have not mentioned are not +sufficient, the |cm| option allows you to apply an arbitrary +transformation matrix. Karl's students, by the way, do not know what a +transformation matrix is. + + + +\subsection{Repeating Things: For-Loops} + +Karl's next aim is to add little ticks on the axes at positions $-1$, +$-1/2$, $1/2$, and $1$. For this, it would be nice to use some kind of +``loop,'' especially since he wishes to do the same thing at each of +these positions. There are different packages for doing this. \LaTeX\ +has its own internal command for this, |pstricks| comes along with the +powerful |\mulitdo| command. All of these can be used together with +\pgfname\ and \tikzname, so if you are familiar with them, feel free to +use them. \pgfname\ introduces yet another command, called |\foreach|, +which I introduced since I could never remember the syntax of the other +packages. |\foreach| is defined in the package |pgffor| and can be used +independently of \pgfname. \tikzname\ includes it automatically. + +In its basic form, the |\foreach| command is easy to use: +\begin{codeexample}[] +\foreach \x in {1,2,3} {$x =\x$, } +\end{codeexample} + +The general syntax is |\foreach| \meta{variable}| in {|\meta{list of + values}|} |\meta{commands}. Inside the \meta{commands}, the +\meta{variable} will be assigned to the different values. If the +\meta{commands} do not start with a brace, everything up to the +next semicolon is used as \meta{commands}. + +For Karl and the ticks on the axes, he could use the following code: + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip (-0.1,-0.2) rectangle (1.1,1.51); + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc + (0:30:3mm) -- cycle; + \draw[->] (-1.5,0) -- (1.5,0); + \draw[->] (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + + \foreach \x in {-1cm,-0.5cm,1cm} + \draw (\x,-1pt) -- (\x,1pt); + \foreach \y in {-1cm,-0.5cm,0.5cm,1cm} + \draw (-1pt,\y) -- (1pt,\y); +\end{tikzpicture} +\end{codeexample} + +As a matter of fact, there are many different ways of creating the +ticks. For example, Karl could have put the |\draw ...;| inside curly +braces. He could also have used, say, +\begin{codeexample}[code only] +\foreach \x in {-1,-0.5,1} + \draw[xshift=\x cm] (0pt,-1pt) -- (0pt,1pt); +\end{codeexample} + +Karl is curious what would happen in a more complicated situation +where there are, say, 20 ticks. It seems bothersome to explicitly +mention all these numbers in the set for |\foreach|. Indeed, it is +possible to use |...| inside the |\foreach| statement to iterate over +a large number of values (which must, however, be dimensionless +real numbers) as in the following example: + +\begin{codeexample}[] +\tikz \foreach \x in {1,...,10} + \draw (\x,0) circle (0.4cm); +\end{codeexample} + +If you provide \emph{two} numbers before the |...|, the |\foreach| +statement will use their difference for the stepping: + +\begin{codeexample}[] +\tikz \foreach \x in {-1,-0.5,...,1} + \draw (\x cm,-1pt) -- (\x cm,1pt); +\end{codeexample} + +We can also nest loops to create interesting effects: + +\begin{codeexample}[] +\begin{tikzpicture} + \foreach \x in {1,2,...,5,7,8,...,12} + \foreach \y in {1,...,5} + { + \draw (\x,\y) +(-.5,-.5) rectangle ++(.5,.5); + \draw (\x,\y) node{\x,\y}; + } +\end{tikzpicture} +\end{codeexample} + +The |\foreach| statement can do even trickier stuff, but the above +gives the idea. + + + + +\subsection{Adding Text} + +Karl is, by now, quite satisfied with the picture. However, the most +important parts, namely the labels, are still missing! + +\tikzname\ offers an easy-to-use and powerful system for adding text and, +more generally, complex shapes to a picture at specific positions. The +basic idea is the following: When \tikzname\ is constructing a path and +encounters the keyword |node| in the middle of a path, it +reads a \emph{node specification}. The keyword |node| is typically +followed by some options and then some text between curly braces. This +text is put inside a normal \TeX\ box (if the node specification +directly follows a coordinate, which is usually the case, \tikzname\ is +able to perform some magic so that it is even possible to use verbatim +text inside the boxes) and then placed at the current position, that +is, at the last specified position (possibly shifted a bit, according +to the given options). However, all nodes are drawn only after the +path has been completely drawn/filled/shaded/clipped/whatever. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) rectangle (2,2); + \draw (0.5,0.5) node [fill=examplefill] + {Text at \verb!node 1!} + -- (1.5,1.5) node {Text at \verb!node 2!}; +\end{tikzpicture} +\end{codeexample} + +Obviously, Karl would not only like to place nodes \emph{on} the last +specified position, but also to the left or the +right of these positions. For this, every node object that you +put in your picture is equipped with several \emph{anchors}. For +example, the |north| anchor is in the middle at the upper end of the shape, +the |south| anchor is at the bottom and the |north east| anchor is in +the upper right corner. When you given the option |anchor=north|, the +text will be placed such that this northern anchor will lie on the +current position and the text is, thus, below the current +position. Karl uses this to draw the ticks as follows: + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip (-0.6,-0.2) rectangle (0.6,1.51); + \draw[step=.5cm,style=help lines] (-1.4,-1.4) grid (1.4,1.4); + \filldraw[fill=green!20,draw=green!50!black] + (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; + \draw[->] (-1.5,0) -- (1.5,0); \draw[->] (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + + \foreach \x in {-1,-0.5,1} + \draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north] {$\x$}; + \foreach \y in {-1,-0.5,0.5,1} + \draw (1pt,\y cm) -- (-1pt,\y cm) node[anchor=east] {$\y$}; +\end{tikzpicture} +\end{codeexample} + +This is quite nice, already. Using these anchors, Karl can now add +most of the other text elements. However, Karl thinks that, though +``correct,'' it is quite counter-intuitive that in order to place something +\emph{below} a given point, he has to use the \emph{north} anchor. For +this reason, there is an option called |below|, which does the +same as |anchor=north|. Similarly, |above right| does the same as +|anchor=south east|. In addition, |below| takes an optional +dimension argument. If given, the shape will additionally be shifted +downwards by the given amount. So, |below=1pt| can be used to put +a text label below some point and, additionally shift it 1pt +downwards. + +Karl is not quite satisfied with the ticks. He would like to have +$1/2$ or $\frac{1}{2}$ shown instead of $0.5$, partly to show off the +nice capabilities of \TeX\ and \tikzname, partly because for positions +like $1/3$ or $\pi$ it is certainly very much preferable to have the +``mathematical'' tick there instead of just the ``numeric'' tick. +His students, on the other hand, prefer $0.5$ over $1/2$ +since they are not too fond of fractions in general. + +Karl now faces a problem: For the |\foreach| statement, the position +|\x| should still be given as |0.5| since \tikzname\ will not know where +|\frac{1}{2}| is supposed to be. On the other hand, the typeset text +should really be |\frac{1}{2}|. To solve this problem, |\foreach| +offers a special syntax: Instead of having one variable |\x|, Karl can +specify two (or even more) variables separated by a slash as in +|\x / \xtext|. Then, the elements in the set over which |\foreach| +iterates must also be of the form \meta{first}|/|\meta{second}. In +each iteration, |\x| will be set to \meta{first} and |\xtext| will be +set to \meta{second}. If no \meta{second} is given, the \meta{first} +will be used again. So, here is the new code for the ticks: + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip (-0.6,-0.2) rectangle (0.6,1.51); + \draw[step=.5cm,style=help lines] (-1.4,-1.4) grid (1.4,1.4); + \filldraw[fill=green!20,draw=green!50!black] + (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; + \draw[->] (-1.5,0) -- (1.5,0); \draw[->] (0,-1.5) -- (0,1.5); + \draw (0,0) circle (1cm); + + \foreach \x/\xtext in {-1, -0.5/-\frac{1}{2}, 1} + \draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north] {$\xtext$}; + \foreach \y/\ytext in {-1, -0.5/-\frac{1}{2}, 0.5/\frac{1}{2}, 1} + \draw (1pt,\y cm) -- (-1pt,\y cm) node[anchor=east] {$\ytext$}; +\end{tikzpicture} +\end{codeexample} + +Karl is quite pleased with the result, but his son points out that +this is still not perfectly satisfactory: The grid and the circle +interfere with the numbers and decrease their legibility. Karl is not +very concerned by this (his students do not even notice), but his son +insists that there is an easy solution: Karl can add the +|[fill=white]| option to fill out the background of the text shape +with a white color. + +The next thing Karl wants to do is to add the labels like $\sin +\alpha$. For this, he would like to place a label ``in the middle of +line.'' To do so, instead of specifying the label +|node {$\sin\alpha$}| directly after one of the endpoints of the line +(which would place +the label at that endpoint), Karl can give the label directly after +the |--|, before the coordinate. By default, this places the label in +the middle of the line, but the |pos=| options can be used to modify +this. Also, options like |near start| and |near end| can be used to +modify this position: + + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \clip (-2,-0.2) rectangle (2,0.8); + \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); + \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc + (0:30:3mm) -- cycle; + \draw[->] (-1.5,0) -- (1.5,0) coordinate (x axis); + \draw[->] (0,-1.5) -- (0,1.5) coordinate (y axis); + \draw (0,0) circle (1cm); + + \draw[very thick,red] + (30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} (30:1cm |- x axis); + \draw[very thick,blue] + (30:1cm |- x axis) -- node[below=2pt,fill=white] {$\cos \alpha$} (0,0); + \draw[very thick,orange] (1,0) -- node [right=1pt,fill=white] + {$\displaystyle \tan \alpha \color{black}= + \frac{{\color{red}\sin \alpha}}{\color{blue}\cos \alpha}$} + (intersection of 0,0--30:1cm and 1,0--1,1) coordinate (t); + + \draw (0,0) -- (t); + + \foreach \x/\xtext in {-1, -0.5/-\frac{1}{2}, 1} + \draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north,fill=white] {$\xtext$}; + \foreach \y/\ytext in {-1, -0.5/-\frac{1}{2}, 0.5/\frac{1}{2}, 1} + \draw (1pt,\y cm) -- (-1pt,\y cm) node[anchor=east,fill=white] {$\ytext$}; +\end{tikzpicture} +\end{codeexample} + +You can also position labels on curves and, by adding the |sloped| +option, have them rotated such that they match the line's slope. Here +is an example: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) .. controls (6,1) and (9,1) .. + node[near start,sloped,above] {near start} + node {midway} + node[very near end,sloped,below] {very near end} (12,0); +\end{tikzpicture} +\end{codeexample} + +It remains to draw the explanatory text at the right of the +picture. The main difficulty here lies in limiting the width of the +text ``label,'' which is quite long, so that line breaking is +used. Fortunately, Karl can use the option |text width=6cm| to get the +desired effect. So, here is the full code: + +\begin{codeexample}[code only] +\begin{tikzpicture}[scale=3,cap=round] + % Local definitions + \def\costhirty{0.8660256} + + % Colors + \colorlet{anglecolor}{green!50!black} + \colorlet{sincolor}{red} + \colorlet{tancolor}{orange!80!black} + \colorlet{coscolor}{blue} + + % Styles + \tikzstyle{axes}=[] + \tikzstyle{important line}=[very thick] + \tikzstyle{information text}=[rounded corners,fill=red!10,inner sep=1ex] + + % The graphic + \draw[style=help lines,step=0.5cm] (-1.4,-1.4) grid (1.4,1.4); + + \draw (0,0) circle (1cm); + + \begin{scope}[style=axes] + \draw[->] (-1.5,0) -- (1.5,0) node[right] {$x$} coordinate(x axis); + \draw[->] (0,-1.5) -- (0,1.5) node[above] {$y$} coordinate(y axis); + + \foreach \x/\xtext in {-1, -.5/-\frac{1}{2}, 1} + \draw[xshift=\x cm] (0pt,1pt) -- (0pt,-1pt) node[below,fill=white] {$\xtext$}; + + \foreach \y/\ytext in {-1, -.5/-\frac{1}{2}, .5/\frac{1}{2}, 1} + \draw[yshift=\y cm] (1pt,0pt) -- (-1pt,0pt) node[left,fill=white] {$\ytext$}; + \end{scope} + + \filldraw[fill=green!20,draw=anglecolor] (0,0) -- (3mm,0pt) arc(0:30:3mm); + \draw (15:2mm) node[anglecolor] {$\alpha$}; + + \draw[style=important line,sincolor] + (30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} (30:1cm |- x axis); + + \draw[style=important line,coscolor] + (30:1cm |- x axis) -- node[below=2pt,fill=white] {$\cos \alpha$} (0,0); + + \draw[style=important line,tancolor] (1,0) -- node[right=1pt,fill=white] { + $\displaystyle \tan \alpha \color{black}= + \frac{{\color{sincolor}\sin \alpha}}{\color{coscolor}\cos \alpha}$} + (intersection of 0,0--30:1cm and 1,0--1,1) coordinate (t); + + \draw (0,0) -- (t); + + \draw[xshift=1.85cm] + node[right,text width=6cm,style=information text] + { + The {\color{anglecolor} angle $\alpha$} is $30^\circ$ in the + example ($\pi/6$ in radians). The {\color{sincolor}sine of + $\alpha$}, which is the height of the red line, is + \[ + {\color{sincolor} \sin \alpha} = 1/2. + \] + By the Theorem of Pythagoras ... + }; +\end{tikzpicture} +\end{codeexample} + + +\subsection{Nodes} + +Placing text at a given position is just a special case of a more +general underlying mechanism. When you say |\draw (0,0) node{text};|, +what actually happens is that a rectangular node, anchored at its center, is +put at position $(0,0)$. On top of the rectangular node the text +|text| is drawn. Since no action is specified for the rectangle (like +|draw| or |fill|), the rectangle is actually discarded and only the +text is shown. However, by adding |fill| or |draw|, we can make the +underlying shape visible. Furthermore, we can \emph{change} the +shape using for example |shape=circle| or just |circle|. If we include +the package |pgflibraryshapes| we also get |ellipse|: + + +\begin{codeexample}[] +\begin{tikzpicture} + \path (0,0) node[ellipse,fill=examplefill,draw] + (h1) {hello world} + (0.5,2) node[circle,shade,ball color=examplefill] + (h2) {hello world}; + \draw [->,shorten >=2pt] (h1.north) -- (h2.south); +\end{tikzpicture} +\end{codeexample} + +As the above example shows, we can add the a name to a node by +putting it in parentheses between |node| and the |{|\meta{text}|}| +(you can also use the |name=| option). This will make \tikzname\ remember your node and all +its anchors. You can then refer to these anchors when specifying +coordinates. The syntax is |(|\meta{node + name}|.|\meta{anchor}|)|. Currently, and also in the near future, +\emph{this will not work across pictures since \tikzname\ looses track + of the positions when it returns control to \TeX.} Magic hackery is +possible for certain drivers, but a portable implementation seems +impossible (just think of a possible \textsc{svg} driver). + +The option |shorten >| causes lines to be shortened by 2pt at the +end. Similarly, |shorten <| can be used to shorten (or even lengthen) +lines at the beginning. This is possible even if no arrow is drawn. + +It is not always necessary to specify the anchor. If you do not give +an anchor, \tikzname\ will try to determine a reasonable border anchor by +itself (if \tikzname\ fails to find anything useful, it will use the +center instead). Here is a typical example: + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{scope}[shape=circle,minimum size=1cm,fill=examplefill] + \tikzstyle{every node}=[draw,fill] + \node (q_A) at (0,0) {$q_A$}; + \node (q_E) at (6,0) {$q_E$}; + \node (q_1) at (2,0) {$q_1$}; + \node (q_2) at (4,2) {$q_2$}; + \end{scope} + \draw (q_A) -- (q_1) -- (q_2) -| (q_E); + \draw[->,shorten >=2pt] (q_A) .. controls +(75:1.4cm) and +(105:1.4cm) .. node[above] {$x$} (q_A); +\end{tikzpicture} +\end{codeexample} + +In the example, we used the |\node| command, which is an abbreviation +for |\path node|. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-xxcolor.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-xxcolor.tex new file mode 100644 index 00000000000..3e093a58174 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-xxcolor.tex @@ -0,0 +1,87 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + +\section{Extended Color Support} + +This section documents the package \texttt{xxcolor}, which is +currently distributed as part of \pgfname. This package extends the +\texttt{xcolor} package, written by Uwe Kern, which in turn extends +the \texttt{color} package. I hope that the commands in +\texttt{xxcolor} will some day migrate to \texttt{xcolor}, such that +this package becomes superfluous. + +The main aim of the \texttt{xxcolor} package is to provide an +environment inside which all colors are ``washed out'' or ``dimmed.'' +This is useful in numerous situations and must typically be achieved +in a roundabout manner if such an environment is not available. + +\begin{environment}{{colormixin}\marg{mix-in specification}} + The mix-in specification is applied to all colors inside + the environment. At the beginning of the environment, the mix-in is + applied to the current color, i.\,e., the color that was in effect + before the environment started. A mix-in specification is a number + between 0 and 100 followed by an exclamation mark and a color + name. When a |\color| command is + encountered inside a mix-in environment, the number states what + percentage of the desired color should be used. The rest is + ``filled up'' with the color given in the mix-in + specification. Thus, a mix-in specification like |90!blue| + will mix in 10\% of blue into everything, whereas |25!white| will + make everything nearly white. + +\begin{codeexample}[width=4cm] +\begin{minipage}{3.5cm}\raggedright +\color{red}Red text,% +\begin{colormixin}{25!white} + washed-out red text, + \color{blue} washed-out blue text, + \begin{colormixin}{25!black} + dark washed-out blue text, + \color{green} dark washed-out green text,% + \end{colormixin} + back to washed-out blue text,% +\end{colormixin} +and back to red. +\end{minipage}% +\end{codeexample} +\end{environment} + +Note that the environment only changes colors that have been installed +using the standard \LaTeX\ |\color| command. In particular, +the colors in images are not changed. There is, however, some support +offered by the commands |\pgfuseimage| and +|\pgfuseshading|. If the first command is invoked +inside a |colormixin| environment with the parameter, say, +|50!black| on an image with the name |foo|, the command +will first check whether there is also a defined image with the name +|foo.!50!black|. If so, this image is used instead. This allows +you to provide a different image for this case. If you nest +|colormixin| environments, the different mix-ins are all appended. For +example, inside the inner environment of +the above example, |\pgfuseimage{foo}| would first check whether +there exists an image named |foo.!50!white!25!black|. + +\begin{command}{\colorcurrentmixin} + Expands to the current accumulated mix-in. Each nesting of a + |colormixin| adds a mix-in to this list. +\begin{codeexample}[] +\begin{minipage}{\linewidth-6pt}\raggedright +\begin{colormixin}{75!white} + \colorcurrentmixin\ should be ``!75!white''\par + \begin{colormixin}{75!black} + \colorcurrentmixin\ should be ``!75!black!75!white''\par + \begin{colormixin}{50!white} + \colorcurrentmixin\ should be ``!50!white!75!black!75!white''\par + \end{colormixin} + \end{colormixin} +\end{colormixin} +\end{minipage} +\end{codeexample} +\end{command} + + + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-main.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-main.tex new file mode 100644 index 00000000000..d2ea9300f71 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-main.tex @@ -0,0 +1,335 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + +% pgf version is defined in \pgfversion in file +% generic/pgf/utilities/pgfrcs.code.tex + +\def\xcolorversion{2.00} +\def\xkeyvalversion{1.8} + +\usepackage[version=0.96]{pgf} +\usepackage{tikz} +\usepackage{pgflibraryarrows} +\usepackage{pgflibraryshapes} +\usepackage{pgflibraryplotmarks} +\usepackage{pgflibrarytikzbackgrounds} +\usepackage{pgflibrarytikztrees} +\usepackage[left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry} +\usepackage{amsmath,amssymb} +\usepackage{xxcolor} +\usepackage{pifont} +\usepackage{makeidx} +\usepackage[latin1]{inputenc} +\usepackage{amsmath} + +\input{../../macros/pgfmanual-macros} + +\makeindex + +\makeatletter +\renewcommand*\l@subsection{\@dottedtocline{2}{1.5em}{2.8em}} +\renewcommand*\l@subsubsection{\@dottedtocline{3}{4.3em}{3.2em}} +\makeatother + +%\includeonly{pgfmanual-libraries} + +% Global styles: +\tikzstyle{every plot}=[prefix=plots/pgf-] +\tikzstyle{shape example}=[color=black!30,draw,fill=yellow!30,line width=.5cm,inner xsep=2.5cm,inner ysep=0.5cm] + +\index{Options for graphics|see{Graphic options}} +\index{Options for packages|see{Package options}} +\index{File|see{Packages and files}} +\index{Layout|see{Page layout}} + +\begin{document} + +{ + \parindent0pt +\vbox{} +\vskip 3.5cm +\Huge +\tikzname\ and \pgfname + +\Large +Manual for Version \pgfversion + +\vskip 3cm + +\begin{codeexample}[graphic=white] +\tikz[rotate=30] + \foreach \x / \xcolor in {0/blue,1/cyan,2/green,3/yellow,4/red} + \foreach \y / \ycolor in {0/blue,1/cyan,2/green,3/yellow,4/red} + \shade[ball color=\xcolor!50!\ycolor] (\x,\y) circle (7.5mm); +\end{codeexample} +\vskip 0cm plus 1.5fill +\vbox{} +\clearpage +} + +{ + \vbox{} + \vskip0pt plus 1fill + Für meinen Vater, damit er noch viele schöne \TeX-Graphiken erschaffen kann. + \vskip0pt plus 3fill + \vbox{} + \clearpage +} + + +\title{The \tikzname\ and \pgfname\ Packages\\ + Manual for Version \pgfversion\\[1mm] +\large\href{http://sourceforge.net/projects/pgf}{\texttt{http://sourceforge.net/projects/pgf}}} +\author{Till Tantau\\ + \href{mailto:tantau@users.sourceforge.net}{\texttt{tantau@users.sourceforge.net}}} + +\maketitle + +\tableofcontents + +\clearpage + +\part{Getting Started} + +This part is intended to help you get started with the \pgfname\ +package. First, the installation process is explained; however, the +system will typically be already installed on your system, so this can +often be skipped. Next, a short tutorial is given that explains the +most often used commands and concepts of \tikzname, without going into +any of the glorious details. At the end of this section you will find +some, hopefully useful, hints on how to create ``good'' graphics in +general. The information in this section is not specific to +\pgfname. + +\vskip3cm + +\begin{codeexample}[graphic=white,width=0pt] +\tikz \draw[thick,rounded corners=8pt] + (0,0) -- (0,2) -- (1,3.25) -- (2,2) -- (2,0) -- (0,2) -- (2,2) -- (0,0) -- (2,0); +\end{codeexample} + +\include{pgfmanual-introduction} +\include{pgfmanual-installation} +\include{pgfmanual-tutorial} +\include{pgfmanual-guidelines} +\include{pgfmanual-drivers} + + +\part{Ti\emph{k}Z ist \emph{kein} Zeichenprogramm} +\label{part-tikz} + +\vskip3cm +\begin{codeexample}[graphic=white] +\begin{tikzpicture} + \draw[fill=yellow] (0,0) -- (60:.75cm) arc (60:180:.75cm); + \draw(120:0.4cm) node {$\alpha$}; + + \draw[fill=green!30] (0,0) -- (right:.75cm) arc (0:60:.75cm); + \draw(30:0.5cm) node {$\beta$}; + + \begin{scope}[shift={(60:2cm)}] + \draw[fill=green!30] (0,0) -- (180:.75cm) arc (180:240:.75cm); + \draw (30:-0.5cm) node {$\gamma$}; + + \draw[fill=yellow] (0,0) -- (240:.75cm) arc (240:360:.75cm); + \draw (-60:0.4cm) node {$\delta$}; + \end{scope} + + \begin{scope}[thick] + \draw (60:-1cm) node[fill=white] {$E$} -- (60:3cm) node[fill=white] {$F$}; + \draw[red] (-2,0) node[left] {$A$} -- (3,0) node[right]{$B$}; + \draw[blue,shift={(60:2cm)}] (-3,0) node[left] {$C$} -- (2,0) node[right]{$D$}; + + \draw[shift={(60:1cm)},xshift=4cm] + node [right,text width=6cm,rounded corners,fill=red!20,inner sep=1ex] + { + When we assume that $\color{red}AB$ and $\color{blue}CD$ are + parallel, i.\,e., ${\color{red}AB} \mathbin{\|} \color{blue}CD$, + then $\alpha = \delta$ and $\beta = \gamma$. + }; + \end{scope} +\end{tikzpicture} +\end{codeexample} + + + +\include{pgfmanual-tikz-design} +\include{pgfmanual-tikz-scopes} +\include{pgfmanual-tikz-coordinates} +\include{pgfmanual-tikz-paths} +\include{pgfmanual-tikz-actions} +\include{pgfmanual-tikz-shapes} +\include{pgfmanual-tikz-trees} +\include{pgfmanual-tikz-transformations} + + + +\part{Libraries and Utilities} +\label{part-libraries} + +In this part the library and utility packages are documented. The +library packages provide additional predefined graphic objects like +new arrow heads, or new plot marks. These are not loaded by default +since many users will not need them. + +The utility packages are not directly involved in creating graphics, +but you may find them useful nonetheless. All of them either directly +depend on \pgfname\ or they are designed to work well together with +\pgfname\ even though they can be used in a stand-alone way. +\vskip2cm +\medskip +\noindent +\begin{codeexample}[graphic=white] +\begin{tikzpicture}[scale=2] + \shade[top color=blue,bottom color=gray!50] (0,0) parabola (1.5,2.25) |- (0,0); + \draw (1.05cm,2pt) node[above] {$\displaystyle\int_0^{3/2} \!\!x^2\mathrm{d}x$}; + + \draw[style=help lines] (0,0) grid (3.9,3.9) + [step=0.25cm] (1,2) grid +(1,1); + + \draw[->] (-0.2,0) -- (4,0) node[right] {$x$}; + \draw[->] (0,-0.2) -- (0,4) node[above] {$f(x)$}; + + \foreach \x/\xtext in {1/1, 1.5/1\frac{1}{2}, 2/2, 3/3} + \draw[shift={(\x,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\xtext$}; + + \foreach \y/\ytext in {1/1, 2/2, 2.25/2\frac{1}{4}, 3/3} + \draw[shift={(0,\y)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\ytext$}; + + \draw (-.5,.25) parabola bend (0,0) (2,4) node[below right] {$x^2$}; +\end{tikzpicture} +\end{codeexample} + +\include{pgfmanual-libraries} +\include{pgfmanual-pgffor} +\include{pgfmanual-pages} +\include{pgfmanual-xxcolor} + + + +\part{The Basic Layer} + +\vskip1cm +\begin{codeexample}[graphic=white] +\begin{tikzpicture} + \draw[gray,very thin] (-1.9,-1.9) grid (2.9,3.9) + [step=0.25cm] (-1,-1) grid (1,1); + \draw[blue] (1,-2.1) -- (1,4.1); % asymptote + + \draw[->] (-2,0) -- (3,0) node[right] {$x(t)$}; + \draw[->] (0,-2) -- (0,4) node[above] {$y(t)$}; + + \foreach \pos in {-1,2} + \draw[shift={(\pos,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\pos$}; + + \foreach \pos in {-1,1,2,3} + \draw[shift={(0,\pos)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\pos$}; + + \fill (0,0) circle (0.064cm); + \draw[thick,parametric,domain=0.4:1.5,samples=200] + % The plot is reparameterised such that there are more samples + % near the center. + plot[id=asymptotic-example] function{(t*t*t)*sin(1/(t*t*t)),(t*t*t)*cos(1/(t*t*t))} + node[right] {$\bigl(x(t),y(t)\bigr) = (t\sin \frac{1}{t}, t\cos \frac{1}{t})$}; + + \fill[red] (0.63662,0) circle (2pt) + node [below right,fill=white,yshift=-4pt] {$(\frac{2}{\pi},0)$}; +\end{tikzpicture} +\end{codeexample} + + +\include{pgfmanual-base-design} +\include{pgfmanual-base-scopes} +\include{pgfmanual-base-points} +\include{pgfmanual-base-paths} +\include{pgfmanual-base-actions} +\include{pgfmanual-base-arrows} +\include{pgfmanual-base-nodes} +\include{pgfmanual-base-transformations} +\include{pgfmanual-base-images} +\include{pgfmanual-base-shadings} +\include{pgfmanual-base-plots} +\include{pgfmanual-base-layers} +\include{pgfmanual-base-quick} + + + + +\part{The System Layer} +\label{part-system} + +This part describes the low-level interface of \pgfname, called the +\emph{system layer}. This interface provides a complete abstraction of +the internals of the underlying drivers. + +Unless you intend to port \pgfname\ to another driver or unless you intend +to write your own optimized frontend, you need not read this part. + +In the following it is assumed that you are familiar with the basic +workings of the |graphics| package and that you know what +\TeX-drivers are and how they work. + +\vskip1cm +\begin{codeexample}[graphic=white] +\begin{tikzpicture}[shorten >=1pt,->] + \tikzstyle{vertex}=[circle,fill=black!25,minimum size=17pt,inner sep=0pt] + + \foreach \name/\x in {s/1, 2/2, 3/3, 4/4, 15/11, 16/12, 17/13, 18/14, 19/15, t/16} + \node[vertex] (G-\name) at (\x,0) {$\name$}; + + \foreach \name/\angle/\text in {P-1/234/5, P-2/162/6, P-3/90/7, P-4/18/8, P-5/-54/9} + \node[vertex,xshift=6cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$}; + + \foreach \name/\angle/\text in {Q-1/234/10, Q-2/162/11, Q-3/90/12, Q-4/18/13, Q-5/-54/14} + \node[vertex,xshift=9cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$}; + + \foreach \from/\to in {s/2,2/3,3/4,3/4,15/16,16/17,17/18,18/19,19/t} + \draw (G-\from) -- (G-\to); + + \foreach \from/\to in {1/2,2/3,3/4,4/5,5/1,1/3,2/4,3/5,4/1,5/2} + { \draw (P-\from) -- (P-\to); \draw (Q-\from) -- (Q-\to); } + + \draw (G-3) .. controls +(-30:2cm) and +(-150:1cm) .. (Q-1); + \draw (Q-5) -- (G-15); +\end{tikzpicture} +\end{codeexample} + +\include{pgfmanual-pgfsys-overview} +\include{pgfmanual-pgfsys-commands} +\include{pgfmanual-pgfsys-paths} +\include{pgfmanual-pgfsys-protocol} + + + +\part{References and Index} + +\vskip1cm +\begin{codeexample}[graphic=white] +\begin{tikzpicture} + \draw[line width=0.3cm,color=red!30,cap=round,join=round] (0,0)--(2,0)--(2,5); + \draw[help lines] (-2.5,-2.5) grid (5.5,7.5); + \draw[very thick] (1,-1)--(-1,-1)--(-1,1)--(0,1)--(0,0)-- + (1,0)--(1,-1)--(3,-1)--(3,2)--(2,2)--(2,3)--(3,3)-- + (3,5)--(1,5)--(1,4)--(0,4)--(0,6)--(1,6)--(1,5) + (3,3)--(4,3)--(4,5)--(3,5)--(3,6) + (3,-1)--(4,-1); + \draw[below left] (0,0) node(s){$s$}; + \draw[below left] (2,5) node(t){$t$}; + \fill (0,0) circle (0.06cm) (2,5) circle (0.06cm); + \draw[->,rounded corners=0.2cm,shorten >=2pt] + (1.5,0.5)-- ++(0,-1)-- ++(1,0)-- ++(0,2)-- ++(-1,0)-- ++(0,2)-- ++(1,0)-- + ++(0,1)-- ++(-1,0)-- ++(0,-1)-- ++(-2,0)-- ++(0,3)-- ++(2,0)-- ++(0,-1)-- + ++(1,0)-- ++(0,1)-- ++(1,0)-- ++(0,-1)-- ++(1,0)-- ++(0,-3)-- ++(-2,0)-- + ++(1,0)-- ++(0,-3)-- ++(1,0)-- ++(0,-1)-- ++(-6,0)-- ++(0,3)-- ++(2,0)-- + ++(0,-1)-- ++(1,0); +\end{tikzpicture} +\end{codeexample} + +\printindex + +\end{document} + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-asymptotic-example.gnuplot b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-asymptotic-example.gnuplot new file mode 100644 index 00000000000..4c854afda9f --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-asymptotic-example.gnuplot @@ -0,0 +1,2 @@ +set terminal table; set output "plots/pgf-asymptotic-example.table"; set format "%.5f" +set samples 200; set parametric; plot [t=0.4:1.5] (t*t*t)*sin(1/(t*t*t)),(t*t*t)*cos(1/(t*t*t)) diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-asymptotic-example.table b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-asymptotic-example.table new file mode 100644 index 00000000000..173ab5e9c77 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-asymptotic-example.table @@ -0,0 +1,204 @@ +#Curve 0, 200 points +#x y type +0.00530 -0.06378 i +0.04363 -0.05043 i +0.06711 -0.01790 i +0.06896 0.02170 i +0.05014 0.05606 i +0.01712 0.07631 i +-0.02110 0.07849 i +-0.05579 0.06337 i +-0.08032 0.03512 i +-0.09097 -0.00029 i +-0.08696 -0.03664 i +-0.06987 -0.06850 i +-0.04284 -0.09192 i +-0.00982 -0.10460 i +0.02515 -0.10585 i +0.05841 -0.09629 i +0.08703 -0.07749 i +0.10892 -0.05162 i +0.12282 -0.02111 i +0.12828 0.01163 i +0.12547 0.04436 i +0.11507 0.07518 i +0.09810 0.10255 i +0.07579 0.12534 i +0.04948 0.14280 i +0.02048 0.15454 i +-0.00995 0.16043 i +-0.04065 0.16063 i +-0.07063 0.15545 i +-0.09905 0.14536 i +-0.12521 0.13092 i +-0.14860 0.11273 i +-0.16882 0.09143 i +-0.18562 0.06764 i +-0.19885 0.04197 i +-0.20848 0.01500 i +-0.21454 -0.01276 i +-0.21712 -0.04083 i +-0.21637 -0.06879 i +-0.21247 -0.09627 i +-0.20565 -0.12295 i +-0.19613 -0.14858 i +-0.18415 -0.17294 i +-0.16996 -0.19585 i +-0.15379 -0.21718 i +-0.13589 -0.23682 i +-0.11647 -0.25471 i +-0.09576 -0.27080 i +-0.07396 -0.28508 i +-0.05126 -0.29753 i +-0.02783 -0.30819 i +-0.00384 -0.31707 i +0.02057 -0.32421 i +0.04526 -0.32967 i +0.07011 -0.33350 i +0.09502 -0.33576 i +0.11989 -0.33651 i +0.14463 -0.33582 i +0.16917 -0.33376 i +0.19345 -0.33040 i +0.21741 -0.32580 i +0.24100 -0.32003 i +0.26418 -0.31315 i +0.28691 -0.30524 i +0.30918 -0.29634 i +0.33096 -0.28653 i +0.35222 -0.27585 i +0.37297 -0.26437 i +0.39318 -0.25213 i +0.41285 -0.23918 i +0.43197 -0.22557 i +0.45056 -0.21134 i +0.46860 -0.19654 i +0.48611 -0.18119 i +0.50309 -0.16535 i +0.51954 -0.14904 i +0.53547 -0.13229 i +0.55090 -0.11514 i +0.56582 -0.09761 i +0.58026 -0.07972 i +0.59422 -0.06150 i +0.60772 -0.04298 i +0.62076 -0.02416 i +0.63336 -0.00508 i +0.64554 0.01425 i +0.65729 0.03382 i +0.66864 0.05361 i +0.67960 0.07361 i +0.69018 0.09381 i +0.70039 0.11420 i +0.71024 0.13475 i +0.71975 0.15548 i +0.72892 0.17636 i +0.73778 0.19739 i +0.74632 0.21857 i +0.75456 0.23989 i +0.76251 0.26134 i +0.77018 0.28291 i +0.77759 0.30461 i +0.78473 0.32643 i +0.79162 0.34837 i +0.79826 0.37042 i +0.80468 0.39258 i +0.81087 0.41485 i +0.81684 0.43723 i +0.82261 0.45972 i +0.82817 0.48232 i +0.83354 0.50502 i +0.83872 0.52782 i +0.84372 0.55073 i +0.84855 0.57374 i +0.85321 0.59686 i +0.85772 0.62009 i +0.86206 0.64342 i +0.86626 0.66685 i +0.87032 0.69040 i +0.87423 0.71405 i +0.87801 0.73781 i +0.88167 0.76169 i +0.88520 0.78567 i +0.88861 0.80977 i +0.89191 0.83398 i +0.89510 0.85831 i +0.89818 0.88276 i +0.90115 0.90733 i +0.90403 0.93202 i +0.90682 0.95683 i +0.90951 0.98177 i +0.91211 1.00683 i +0.91463 1.03202 i +0.91707 1.05735 i +0.91942 1.08280 i +0.92171 1.10839 i +0.92391 1.13411 i +0.92605 1.15998 i +0.92812 1.18598 i +0.93012 1.21213 i +0.93205 1.23842 i +0.93393 1.26485 i +0.93575 1.29143 i +0.93751 1.31817 i +0.93921 1.34505 i +0.94086 1.37209 i +0.94246 1.39929 i +0.94401 1.42664 i +0.94552 1.45415 i +0.94697 1.48183 i +0.94838 1.50967 i +0.94975 1.53767 i +0.95108 1.56584 i +0.95236 1.59418 i +0.95361 1.62270 i +0.95482 1.65138 i +0.95600 1.68025 i +0.95713 1.70928 i +0.95824 1.73850 i +0.95931 1.76790 i +0.96035 1.79748 i +0.96136 1.82725 i +0.96234 1.85720 i +0.96329 1.88735 i +0.96422 1.91768 i +0.96511 1.94820 i +0.96598 1.97892 i +0.96683 2.00983 i +0.96765 2.04094 i +0.96845 2.07225 i +0.96922 2.10376 i +0.96998 2.13547 i +0.97071 2.16739 i +0.97142 2.19952 i +0.97211 2.23185 i +0.97278 2.26439 i +0.97344 2.29714 i +0.97407 2.33010 i +0.97469 2.36328 i +0.97529 2.39667 i +0.97588 2.43028 i +0.97644 2.46411 i +0.97700 2.49817 i +0.97754 2.53244 i +0.97806 2.56694 i +0.97857 2.60166 i +0.97906 2.63661 i +0.97955 2.67179 i +0.98001 2.70720 i +0.98047 2.74284 i +0.98092 2.77871 i +0.98135 2.81482 i +0.98177 2.85117 i +0.98218 2.88775 i +0.98258 2.92457 i +0.98297 2.96163 i +0.98335 2.99894 i +0.98372 3.03649 i +0.98408 3.07428 i +0.98443 3.11232 i +0.98477 3.15061 i +0.98511 3.18914 i +0.98543 3.22793 i + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-exp.gnuplot b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-exp.gnuplot new file mode 100644 index 00000000000..1d34e313af8 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-exp.gnuplot @@ -0,0 +1,2 @@ +set terminal table; set output "plots/pgf-exp.table"; set format "%.5f" +set samples 25; plot [x=0:4] 0.05*exp(x) diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-exp.table b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-exp.table new file mode 100644 index 00000000000..8e728570397 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-exp.table @@ -0,0 +1,29 @@ +#Curve 0, 25 points +#x y type +0.00000 0.05000 i +0.16667 0.05907 i +0.33333 0.06978 i +0.50000 0.08244 i +0.66667 0.09739 i +0.83333 0.11505 i +1.00000 0.13591 i +1.16667 0.16056 i +1.33333 0.18968 i +1.50000 0.22408 i +1.66667 0.26472 i +1.83333 0.31274 i +2.00000 0.36945 i +2.16667 0.43646 i +2.33333 0.51561 i +2.50000 0.60912 i +2.66667 0.71960 i +2.83333 0.85010 i +3.00000 1.00428 i +3.16667 1.18641 i +3.33333 1.40158 i +3.50000 1.65577 i +3.66667 1.95606 i +3.83333 2.31082 i +4.00000 2.72991 i + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-parametric-example.gnuplot b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-parametric-example.gnuplot new file mode 100644 index 00000000000..e1c3f3b52f2 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-parametric-example.gnuplot @@ -0,0 +1,2 @@ +set terminal table; set output "plots/pgf-parametric-example.table"; set format "%.5f" +set samples 25; set parametric; plot [t=-3.141:3.141] t*sin(t),t*cos(t) diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-parametric-example.table b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-parametric-example.table new file mode 100644 index 00000000000..de0c383ddde --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-parametric-example.table @@ -0,0 +1,29 @@ +#Curve 0, 25 points +#x y type +0.00186 3.14100 i +0.74672 2.78074 i +1.30987 2.26617 i +1.66651 1.66503 i +1.81387 1.04628 i +1.76998 0.47361 i +1.57050 -0.00047 i +1.26407 -0.33904 i +0.90663 -0.52368 i +0.55517 -0.55534 i +0.26171 -0.45339 i +0.06773 -0.25283 i +0.00000 -0.00000 i +0.06773 0.25283 i +0.26171 0.45339 i +0.55517 0.55534 i +0.90663 0.52368 i +1.26407 0.33904 i +1.57050 0.00047 i +1.76998 -0.47361 i +1.81387 -1.04628 i +1.66651 -1.66503 i +1.30987 -2.26617 i +0.74672 -2.78074 i +0.00186 -3.14100 i + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-sin.gnuplot b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-sin.gnuplot new file mode 100644 index 00000000000..884d534bf4a --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-sin.gnuplot @@ -0,0 +1,2 @@ +set terminal table; set output "plots/pgf-sin.table"; set format "%.5f" +set samples 25; plot [x=0:4] sin(x) diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-sin.table b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-sin.table new file mode 100644 index 00000000000..9ab8f2c8d56 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-sin.table @@ -0,0 +1,29 @@ +#Curve 0, 25 points +#x y type +0.00000 0.00000 i +0.16667 0.16590 i +0.33333 0.32719 i +0.50000 0.47943 i +0.66667 0.61837 i +0.83333 0.74018 i +1.00000 0.84147 i +1.16667 0.91944 i +1.33333 0.97194 i +1.50000 0.99749 i +1.66667 0.99541 i +1.83333 0.96573 i +2.00000 0.90930 i +2.16667 0.82766 i +2.33333 0.72309 i +2.50000 0.59847 i +2.66667 0.45727 i +2.83333 0.30340 i +3.00000 0.14112 i +3.16667 -0.02507 i +3.33333 -0.19057 i +3.50000 -0.35078 i +3.66667 -0.50128 i +3.83333 -0.63788 i +4.00000 -0.75680 i + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-x.gnuplot b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-x.gnuplot new file mode 100644 index 00000000000..bb95994cd89 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-x.gnuplot @@ -0,0 +1,2 @@ +set terminal table; set output "plots/pgf-x.table"; set format "%.5f" +set samples 25; plot [x=0:4] x diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-x.table b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-x.table new file mode 100644 index 00000000000..329b9fa56b5 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-x.table @@ -0,0 +1,29 @@ +#Curve 0, 25 points +#x y type +0.00000 0.00000 i +0.16667 0.16667 i +0.33333 0.33333 i +0.50000 0.50000 i +0.66667 0.66667 i +0.83333 0.83333 i +1.00000 1.00000 i +1.16667 1.16667 i +1.33333 1.33333 i +1.50000 1.50000 i +1.66667 1.66667 i +1.83333 1.83333 i +2.00000 2.00000 i +2.16667 2.16667 i +2.33333 2.33333 i +2.50000 2.50000 i +2.66667 2.66667 i +2.83333 2.83333 i +3.00000 3.00000 i +3.16667 3.16667 i +3.33333 3.33333 i +3.50000 3.50000 i +3.66667 3.66667 i +3.83333 3.83333 i +4.00000 4.00000 i + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfmanual-sine.gnuplot b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfmanual-sine.gnuplot new file mode 100644 index 00000000000..8e3f24b9172 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfmanual-sine.gnuplot @@ -0,0 +1,5 @@ +set terminal table +set output "pgfmanual-sine.table" +set format "%.5f" +set samples 20 +plot [x=0:10] sin(x) diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfmanual-sine.table b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfmanual-sine.table new file mode 100644 index 00000000000..9d5d248a561 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfmanual-sine.table @@ -0,0 +1,24 @@ +#Curve 0, 20 points +#x y type +0.00000 0.00000 i +0.52632 0.50235 i +1.05263 0.86873 i +1.57895 0.99997 i +2.10526 0.86054 i +2.63158 0.48819 i +3.15789 -0.01630 i +3.68421 -0.51638 i +4.21053 -0.87669 i +4.73684 -0.99970 i +5.26316 -0.85212 i +5.78947 -0.47390 i +6.31579 0.03260 i +6.84211 0.53027 i +7.36842 0.88441 i +7.89474 0.99917 i +8.42105 0.84348 i +8.94737 0.45948 i +9.47368 -0.04889 i +10.00000 -0.54402 i + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfplotgnuplot-example.gnuplot b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfplotgnuplot-example.gnuplot new file mode 100644 index 00000000000..3bd81ae92d1 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfplotgnuplot-example.gnuplot @@ -0,0 +1,2 @@ +set terminal table; set output "plots/pgfplotgnuplot-example.table"; set format "%.5f" +plot [x=0:3.5] x*sin(x) diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfplotgnuplot-example.table b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfplotgnuplot-example.table new file mode 100644 index 00000000000..a4e517898a8 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgfplotgnuplot-example.table @@ -0,0 +1,104 @@ +#Curve 0, 100 points +#x y type +0.00000 0.00000 i +0.03535 0.00125 i +0.07071 0.00500 i +0.10606 0.01123 i +0.14141 0.01993 i +0.17677 0.03108 i +0.21212 0.04466 i +0.24747 0.06062 i +0.28283 0.07893 i +0.31818 0.09954 i +0.35354 0.12240 i +0.38889 0.14745 i +0.42424 0.17463 i +0.45960 0.20387 i +0.49495 0.23509 i +0.53030 0.26822 i +0.56566 0.30318 i +0.60101 0.33986 i +0.63636 0.37817 i +0.67172 0.41803 i +0.70707 0.45932 i +0.74242 0.50194 i +0.77778 0.54577 i +0.81313 0.59069 i +0.84848 0.63660 i +0.88384 0.68337 i +0.91919 0.73086 i +0.95455 0.77896 i +0.98990 0.82753 i +1.02525 0.87643 i +1.06061 0.92554 i +1.09596 0.97471 i +1.13131 1.02381 i +1.16667 1.07269 i +1.20202 1.12121 i +1.23737 1.16923 i +1.27273 1.21661 i +1.30808 1.26320 i +1.34343 1.30886 i +1.37879 1.35345 i +1.41414 1.39682 i +1.44949 1.43884 i +1.48485 1.47937 i +1.52020 1.51826 i +1.55556 1.55537 i +1.59091 1.59059 i +1.62626 1.62376 i +1.66162 1.65477 i +1.69697 1.68348 i +1.73232 1.70977 i +1.76768 1.73353 i +1.80303 1.75463 i +1.83838 1.77296 i +1.87374 1.78841 i +1.90909 1.80089 i +1.94444 1.81028 i +1.97980 1.81650 i +2.01515 1.81946 i +2.05051 1.81906 i +2.08586 1.81524 i +2.12121 1.80792 i +2.15657 1.79704 i +2.19192 1.78252 i +2.22727 1.76433 i +2.26263 1.74240 i +2.29798 1.71671 i +2.33333 1.68720 i +2.36869 1.65386 i +2.40404 1.61667 i +2.43939 1.57560 i +2.47475 1.53066 i +2.51010 1.48184 i +2.54545 1.42915 i +2.58081 1.37260 i +2.61616 1.31223 i +2.65152 1.24805 i +2.68687 1.18011 i +2.72222 1.10845 i +2.75758 1.03312 i +2.79293 0.95418 i +2.82828 0.87170 i +2.86364 0.78576 i +2.89899 0.69642 i +2.93434 0.60380 i +2.96970 0.50797 i +3.00505 0.40904 i +3.04040 0.30713 i +3.07576 0.20235 i +3.11111 0.09482 i +3.14646 -0.01533 i +3.18182 -0.12796 i +3.21717 -0.24292 i +3.25253 -0.36007 i +3.28788 -0.47926 i +3.32323 -0.60032 i +3.35859 -0.72308 i +3.39394 -0.84739 i +3.42929 -0.97305 i +3.46465 -1.09990 i +3.50000 -1.22774 i + + |