summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex312
1 files changed, 216 insertions, 96 deletions
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
index 0b0b5735c9f..85891e6d9de 100644
--- 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
@@ -27,12 +27,11 @@ apply to everything within the environment.
\begin{package}{tikz}
This package does not have any options.
- This will automatically load the \pgfname\ package and some other
- stuff that \tikzname\ needs (like the |xkeyval| package).
+ This will automatically load the \pgfname\ and the |pgffor| 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
+ for you; this is true in particular if you use \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}|
@@ -54,7 +53,7 @@ apply to everything within the environment.
definitions.
What this command does is to load the file
- |pgflibrarytikz|\meta{library}|.code.tex| for each \meta{library} in
+ |tikzlibrary|\meta{library}|.code.tex| for each \meta{library} in
the \meta{list of libraries}. Thus, to write your own library file,
all you need to do is to place a file of the appropriate name
somewhere where \TeX\ can find it. \LaTeX, plain \TeX, and Con\TeX t
@@ -77,22 +76,22 @@ 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.
+external program. The graphic options are specified in \emph{key
+ lists}, see Section~\ref{section-graphic-options} below for
+details. 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
+ environment, except for the |\tikzset| 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.
+ parsed, see Section~\ref{section-graphic-options}. 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
@@ -105,21 +104,20 @@ options are local to the |{tikzpicture}| to which they apply.
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
+ at the size of a bounding box of the graphic and
+ then resizes the picture 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
+ bounding 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
+ approximation of the bounding box, but will not always be
+ accurate. First, the line thickness of diagonal lines is not taken
+ into account correctly. 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
+ The following key influences the baseline of the resulting
picture:
- \begin{itemize}
- \itemoption{baseline}\opt{|=|\meta{dimension or coordinate}}
+ \begin{key}{/tikz/baseline=\meta{dimension or coordinate} (default 0pt)}
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
@@ -129,10 +127,9 @@ options are local to the |{tikzpicture}| to which they apply.
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);|
+ 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.
+ baseline is on the height of the $x$-axis.
This options is often useful for ``inlined'' graphics as in
\begin{codeexample}[]
@@ -157,19 +154,22 @@ Top align:
\tikz[baseline=(current bounding box.north)]
\draw (0,0) rectangle (1cm,1ex);
\end{codeexample}
+ \end{key}
- \itemoption{execute at begin picture}|=|\meta{code}
- This option can be used to install some code that will be executed
+ \begin{key}{/tikz/execute at begin picture=\meta{code}}
+ This option causes \meta{code} to 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.
+ the picture has already ``started'' later on. The effect of
+ multiply setting this option accumulates.
This option is mainly used in styles like the |every picture|
style to execute certain code at the start of a picture.
+ \end{key}
- \itemoption{execute at end picture}|=|\meta{code}
- This option installs some code that will be executed
+ \begin{key}{/tikz/execute at end picture=\meta{code}}
+ This option installs \meta{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.
@@ -187,17 +187,26 @@ Top align:
\node at (2,1) {Y};
\end{tikzpicture}
\end{codeexample}
- \end{itemize}
-
+ \end{key}
+
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}
+ ``globally'' change the following style:
+ \begin{stylekey}{/tikz/every picture (initially \normalfont empty)}
This style is installed at the beginning of each picture.
\begin{codeexample}[code only]
-\tikzstyle{every picture}=[semithick]
+\tikzset{every picture/.style=semithick}
\end{codeexample}
- \end{itemize}
+ \end{stylekey}
+
+ Note that you should not use |\tikzset| to set options directly. For
+ instance, if you want to use a line width of |1pt| by default, do
+ not try to say |\tikzset{line width=1pt}| at the beginning of your
+ document. This will not work since the line width is changed in many
+ places. Instead, say
+\begin{codeexample}[code only]
+\tikzset{every picture/.style={line width=1pt}}
+\end{codeexample}
+ This will have the desired effect.
\end{environment}
In other \TeX\ format, you should use instead the following commands:
@@ -249,7 +258,7 @@ 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
+|backgrounds|. This package is documented in
Section~\ref{section-tikz-backgrounds}.
@@ -260,6 +269,8 @@ using the |{scope}| environment. This environment is available only
inside the |{tikzpicture}| environment, so once more, there is little
chance of doing anything wrong.
+\subsubsection{The Scope Environment}
+
\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
@@ -267,44 +278,41 @@ chance of doing anything wrong.
``ends'' at its end.
\begin{codeexample}[]
-\begin{tikzpicture}
+\begin{tikzpicture}[ultra thick]
\begin{scope}[red]
- \draw (0mm,0mm) -- (10mm,0mm);
- \draw (0mm,1mm) -- (10mm,1mm);
+ \draw (0mm,10mm) -- (10mm,10mm);
+ \draw (0mm,8mm) -- (10mm,8mm);
\end{scope}
- \draw (0mm,2mm) -- (10mm,2mm);
+ \draw (0mm,6mm) -- (10mm,6mm);
\begin{scope}[green]
- \draw (0mm,3mm) -- (10mm,3mm);
\draw (0mm,4mm) -- (10mm,4mm);
- \draw[blue] (0mm,5mm) -- (10mm,5mm);
+ \draw (0mm,2mm) -- (10mm,2mm);
+ \draw[blue] (0mm,0mm) -- (10mm,0mm);
\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}
+ \begin{stylekey}{/tikz/every scope (initially \normalfont empty)}
+ This style is installed at the beginning of every scope.
+ \end{stylekey}
The following options are useful for scopes:
- \begin{itemize}
- \itemoption{execute at begin scope}|=|\meta{code}
+ \begin{key}{/tikz/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}
+ \end{key}
+ \begin{key}{/tikz/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{key}
\end{environment}
\begin{plainenvironment}{{scope}\opt{\oarg{options}}}
@@ -316,8 +324,48 @@ chance of doing anything wrong.
\end{contextenvironment}
+\subsubsection{Shorthand for Scope Environments}
+
+There is a small library that makes using scopes a bit easier:
+\begin{tikzlibrary}{scopes}
+ This library defines a shorthand for starting and ending |{scope}|
+ environments.
+\end{tikzlibrary}
+When this library is loaded, the following happens: At certain places
+inside a \tikzname\ picture, it is allowed to start a scope just using
+a single brace, provided the single brace is followed by options in
+square brackets:
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ { [ultra thick]
+ { [red]
+ \draw (0mm,10mm) -- (10mm,10mm);
+ \draw (0mm,8mm) -- (10mm,8mm);
+ }
+ \draw (0mm,6mm) -- (10mm,6mm);
+ }
+ { [green]
+ \draw (0mm,4mm) -- (10mm,4mm);
+ \draw (0mm,2mm) -- (10mm,2mm);
+ \draw[blue] (0mm,0mm) -- (10mm,0mm);
+ }
+\end{tikzpicture}
+\end{codeexample}
+
+In the above example, |{ [thick]| actually causes a
+ |\begin{scope}[thick]| to be inserted, and the corresponding closing
+ |}| causes an |\end{scope}| to be inserted.
+
+The ``certain places'' where an opening brace has this special meaning
+are the following: First, right after the semicolon that ends a path. Second,
+right after the end of a scope. Third, right at the beginning of a
+scope, which includes the beginning of a picture. Also note that some
+square bracket must follow, otherwise the brace is treated as a normal
+\TeX\ scope.
-\subsection{Using Scopes Inside Paths}
+
+\subsubsection{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
@@ -341,7 +389,52 @@ the node, not to the surrounding path.
-\subsection{Using Styles to Manage How Pictures Look}
+\subsection{Using Graphic Options}
+\label{section-graphic-options}
+
+\subsubsection{How Graphic Options Are Processed}
+
+Many commands and environments of \tikzname\ accept
+\emph{options}. These options are so-called \emph{key lists}. To
+process the options, the following command is used, which you can also
+call yourself. Note that it is usually better not to call this command
+directly, since this will ensure that the effect of options are local
+to a well-defined scope.
+
+\begin{command}{\tikzset\marg{options}}
+ This command will process the \meta{options} using the |\pgfkeys|
+ command, documented in detail in Section~\ref{section-keys}, with
+ the default path set to |/tikz|. Under normal circumstances, the
+ \meta{options} will be lists of comma-separated pairs of the form
+ \meta{key}|=|\meta{value}, but more fancy things can happen when you
+ use the power of the |pgfkeys| mechanism, see
+ Section~\ref{section-keys} once more.
+
+ When a pair \meta{key}|=|\meta{value} is processed, the following
+ happens:
+ \begin{enumerate}
+ \item If the \meta{key} is a full key (starts with a slash) it is
+ handled directly as described in Section~\ref{section-keys}.
+ \item Otherwise (which is usually the case), it is checked whether
+ |/tikz/|\meta{key} is a key and, if so, it is executed.
+ \item Otherwise, it is checked whether |/pgf/|\meta{key} is a key
+ and, if so, it is executed.
+ \item Otherwise, it is checked whether \meta{key} is a color and, if
+ so, |color=|\meta{key} is executed.
+ \item Otherwise, it is checked whether \meta{key} contains a dash
+ and, if so, |arrows=|\meta{key} is executed.
+ \item Otherwise, it is checked whether \meta{key} is the name of a
+ shape and, if so, |shape=|\meta{key} is executed.
+ \item Otherwise, an error message is printed.
+ \end{enumerate}
+
+ Note that by the above description, all keys starting with |/tikz|
+ and also all keys starting with |/pgf| can be used as \meta{key}s in
+ an \meta{options} list.
+\end{command}
+
+
+\subsubsection{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
@@ -349,66 +442,93 @@ to the normal scoping mechanism. For example, you might wish all your
(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.
+A style is a key that, when used, causes a set of graphic options to
+be processed. Once a style has been defined, it can be used like any
+other key. For example, the predefined |help lines| style, which you
+should use for lines in the background like grid lines or construction
+lines.
\begin{codeexample}[]
\begin{tikzpicture}
- \draw (0,0) grid +(2,2);
- \draw[style=help lines] (2,0) grid +(2,2);
+ \draw (0,0) grid +(2,2);
+ \draw[help lines] (2,0) grid +(2,2);
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+Defining styles is also done using options. Suppose we wish to define
+a style called |my style| and when this style is used, we want the
+draw color to be set to |red| and the fill color be set to
+|red!20|. To achieve this, we use the following option:
+\begin{codeexample}[code only]
+my style/.style={draw=red,fill=red!20}
+\end{codeexample}
-\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.
+The meaning of the curious |/.style| is the following: ``The key
+|my style| should not be used here but, rather, be defined. So, setup
+things such that using the key |my style| will, in the following, have
+the same effect as if we had written |draw=red,fill=red!20| instead.''
- If the style already has a predefined meaning, it will
- unceremoniously be redefined without a warning.
+Returning to the help lines example, suppose we prefer blue help
+lines. This could be achieved as follows:
\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);
+\begin{tikzpicture}[help lines/.style={blue!50,very thin}]
+ \draw (0,0) grid +(2,2);
+ \draw[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:
+Naturally, one of the main ideas behind styles is that they can be
+used in different pictures. In this case, we have to use the
+|\tikzset| command somewhere at the beginning.
\begin{codeexample}[]
-\tikzstyle{help lines}+=[dashed]% aaarghhh!!!
+\tikzset{help lines/.style={blue!50,very thin}}
+% ...
\begin{tikzpicture}
- \draw (0,0) grid +(2,2);
- \draw[style=help lines] (2,0) grid +(2,2);
+ \draw (0,0) grid +(2,2);
+ \draw[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.
+Since styles are just special cases of |pgfkeys|'s general style
+facility, you can actually do quite a bit more. Let us start with
+adding options to an already existing style. This is done using
+|/.append style| instead of |/.style|:
+\begin{codeexample}[]
+\begin{tikzpicture}[help lines/.append style=blue!50]
+ \draw (0,0) grid +(2,2);
+ \draw[help lines] (2,0) grid +(2,2);
+\end{tikzpicture}
+\end{codeexample}
+In the above example, the option |blue!50| is appended to the style
+|help lines|, which now has the same effect as
+|black!50,very thin,blue!50|. Note that two colors are set, so the
+last one will ``win.'' There also exists a handler called
+|/.prefix style| that adds something at the beginning of the style.
+
+Just as normal keys, styles can be parametrized. This means that you
+write \meta{style}|=|\meta{value} when you use the style instead of
+just \meta{style}. In this case, all occurrences of |#1| in
+\meta{style} are replaced by \meta{value}. Here is an example that
+shows how this can be used.
+
\begin{codeexample}[]
-\begin{tikzpicture}[set style={{help lines}+=[dashed]}]
- \draw (0,0) grid +(2,2);
- \draw[style=help lines] (2,0) grid +(2,2);
+\begin{tikzpicture}[outline/.style={draw=#1,thick,fill=#1!50}]
+ \node [outline=red] at (0,1) {red};
+ \node [outline=blue] at (0,0) {blue};
\end{tikzpicture}
\end{codeexample}
-\end{itemize}
+
+For parametrized styles you can also set a \emph{default} value using
+the |/.default| handler:
+
+\begin{codeexample}[]
+\begin{tikzpicture}[outline/.style={draw=#1,thick,fill=#1!50},
+ outline/.default=black]
+ \node [outline] at (0,1) {default};
+ \node [outline=blue] at (0,0) {blue};
+\end{tikzpicture}
+\end{codeexample}
+
+For more details on using and setting styles, see also
+Section~\ref{section-keys}.