diff options
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.tex | 697 |
1 files changed, 349 insertions, 348 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 07d04943cc8..61f0aafb81b 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 @@ -7,146 +7,139 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. -\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. +\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 and the Libraries} \begin{package}{tikz} - This package does not have any options. + This package does not have any options. - This will automatically load the \pgfname\ and the |pgffor| 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 use \LaTeX. One - 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|. + \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 use \LaTeX. One 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} - \begin{command}{\usetikzlibrary\marg{list of libraries}} - Once \tikzname\ has been loaded, you can use this command to load - further libraries. The list of libraries should contain the names of - libraries separated by commas. Instead of curly braces, you can also - use square brackets, which is something Con\TeX t users will - like. If you try to load a library a second time, nothing will - happen. - - \example |\usetikzlibrary{arrows.meta}| - - The above command will load a whole bunch of extra arrow tip - definitions. - - What this command does is to load the file - |tikzlibrary|\meta{library}|.code.tex| for each \meta{library} in - the \meta{list of libraries}. If this file does not exist, the file - |pgflibrary|\meta{library}|.code.tex| is loaded instead. If this - file also does not exist, an error message is printed. 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 users can then use your library. + Once \tikzname\ has been loaded, you can use this command to load further + libraries. The list of libraries should contain the names of libraries + separated by commas. Instead of curly braces, you can also use square + brackets, which is something Con\TeX t users will like. If you try to load + a library a second time, nothing will happen. + + \example |\usetikzlibrary{arrows.meta}| + + The above command will load a whole bunch of extra arrow tip definitions. + + What this command does is to load the file + |tikzlibrary|\meta{library}|.code.tex| for each \meta{library} in the + \meta{list of libraries}. If this file does not exist, the file + |pgflibrary|\meta{library}|.code.tex| is loaded instead. If this file also + does not exist, an error message is printed. 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 users + can then use your library. \end{command} - \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 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 |\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, 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 - 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 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 - bounding box's size such that it encompasses all these - coordinates. This will usually give a good - 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, control 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 key influences the baseline of the resulting - picture: - \begin{key}{/tikz/baseline=\meta{dimension or coordinate or \texttt{default}} (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 - lower end of the picture is at $-.5\mathrm{ex} - 0.2\mathrm{pt}$ - (the 0.2pt are half the line width, which is 0.4pt) and that the - upper end is at $.5\mathrm{ex}+.5\mathrm{pt}$. 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. - - This options is often useful for ``inlined'' graphics as in +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 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{\meta{animations spec}}\opt{\oarg{options}}} + All \tikzname\ commands should be given inside this environment, except for + the |\tikzset| command. You cannot use graphics commands like the low-level + command |\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, see + Section~\ref{section-graphic-options}. All options given here will apply to + the whole picture. Before the options you can specify animation commands, + provided that the |animations| library is loaded, see + Section~\ref{section-tikz-animations} for details. + + 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 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'', every time \pgfname\ + encounters a coordinate, it updates the bounding box's size such that it + encompasses all these coordinates. This will usually give a good + 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, control 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 key influences the baseline of the resulting picture: + % + \begin{key}{/tikz/baseline=\meta{dimension or coordinate or \texttt{default}} (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 lower + end of the picture is at $-.5\mathrm{ex} - 0.2\mathrm{pt}$ (the 0.2pt + are half the line width, which is 0.4pt) and that the upper end is at + $.5\mathrm{ex}+.5\mathrm{pt}$. 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. + + This options is often useful for ``inlined'' graphics as in + % \begin{codeexample}[] $A \mathbin{\tikz[baseline] \draw[->>] (0pt,.5ex) -- (3ex,.5ex);} B$ \end{codeexample} - Instead of a \meta{dimension} you can also provide a coordinate in - parentheses. Then the effect is to put the baseline on the - $y$-coordinate that the given \meta{coordinate} has \emph{at the - end of the picture}. This means that, at the end of the picture, - the \meta{coordinate} is evaluated and then the baseline is set - to the $y$-coordinate of the resulting point. This makes it easy - to reference the $y$-coordinate of, say, the baseline of nodes. + Instead of a \meta{dimension} you can also provide a coordinate in + parentheses. Then the effect is to put the baseline on the + $y$-coordinate that the given \meta{coordinate} has \emph{at the end of + the picture}. This means that, at the end of the picture, the + \meta{coordinate} is evaluated and then the baseline is set to the + $y$-coordinate of the resulting point. This makes it easy to reference + the $y$-coordinate of, say, the baseline of nodes. + % \begin{codeexample}[] Hello \tikz[baseline=(X.base)] @@ -158,28 +151,28 @@ Top align: \tikz[baseline=(current bounding box.north)] \draw (0,0) rectangle (1cm,1ex); \end{codeexample} - - Use |baseline=default| to reset the |baseline| option to its initial configuration. - \end{key} - - \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 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} - - \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. + Use |baseline=default| to reset the |baseline| option to its initial + configuration. + \end{key} + + \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 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} + + \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. + % \begin{codeexample}[] \begin{tikzpicture}[execute at end picture=% { @@ -193,111 +186,108 @@ Top align: \node at (2,1) {Y}; \end{tikzpicture} \end{codeexample} - \end{key} - - All options ``end'' at the end of the picture. To set an option - ``globally'' change the following style: - \begin{stylekey}{/tikz/every picture (initially \normalfont empty)} - This style is installed at the beginning of each picture. + \end{key} + + All options ``end'' at the end of the picture. To set an option + ``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] \tikzset{every picture/.style=semithick} \end{codeexample} - \end{stylekey} + \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 + 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. + % + This will have the desired effect. \end{environment} In other \TeX\ formats, you should use the following commands instead: \begin{plainenvironment}{{tikzpicture}\opt{\oarg{options}}} - This is the plain \TeX\ version of the environment. + This is the plain \TeX\ version of the environment. \end{plainenvironment} \begin{contextenvironment}{{tikzpicture}\opt{\oarg{options}}} - This is the Con\TeX t version of the environment. + This is the Con\TeX t version of the environment. \end{contextenvironment} \subsubsection{Creating a Picture Using a Command} -The following command is an alternative to |{tikzpicture}| that is -particular useful for graphics consisting of a single or few -commands. +The following command is an alternative to |{tikzpicture}| that is particular +useful for graphics consisting of a single or few commands. -\begin{command}{\tikz\opt{\oarg{options}}\marg{path commands}} - This command places the \meta{path commands} inside a - |{tikzpicture}| environment. The \meta{path commands} may - contain paragraphs and fragile material (like verbatim text). +\begin{command}{\tikz\opt{\meta{animations spec}}\opt{\oarg{options}}\marg{path commands}} + This command places the \meta{path commands} inside a |{tikzpicture}| + environment. The \meta{path commands} may contain paragraphs and fragile + material (like verbatim text). - If there is only one path command, it need not be surrounded by - curly braces, if there are several, you need to add them (this is - similar to the |\foreach| statement and also to the rules in - programming languages like Java or C concerning the placement of - curly braces). + If there is only one path command, it need not be surrounded by curly + braces, if there are several, you need to add them (this is similar to the + |\foreach| statement and also to the rules in programming languages like + Java or C concerning the placement of curly braces). - \example |\tikz{\draw (0,0) rectangle (2ex,1ex);}| yields - \tikz{\draw (0,0) rectangle (2ex,1ex);} + \example |\tikz{\draw (0,0) rectangle (2ex,1ex);}| yields + \tikz{\draw (0,0) rectangle (2ex,1ex);} - \example |\tikz \draw (0,0) rectangle (2ex,1ex);| yields - \tikz \draw (0,0) rectangle (2ex,1ex); + \example |\tikz \draw (0,0) rectangle (2ex,1ex);| yields + \tikz \draw (0,0) rectangle (2ex,1ex); \end{command} \subsubsection{Handling Catcodes and the Babel Package} -Inside a \tikzname\ picture, most symbols need to have the category -code 12 (normal text) in order to ensure that the parser works -properly. This is typically not the case when packages like |babel| -are used, which change catcodes aggressively. +Inside a \tikzname\ picture, most symbols need to have the category code 12 +(normal text) in order to ensure that the parser works properly. This is +typically not the case when packages like |babel| are used, which change +catcodes aggressively. -To solve this problem, \tikzname\ provides a small library also called -|babel| (which can, however, also be used together with any other -package that globally changes category codes). What it does is to -reset the category codes at the beginning of every |{tikzpicture}| and -to restore them at the beginning of every node. In almost all cases, -this is exactly would you would expect and need, so I recommend to -always load this library by saying |\usetikzlibrary{babel}|. For -details on what, exactly, happens with the category codes, see -Section~\ref{section-library-babel}. +To solve this problem, \tikzname\ provides a small library also called |babel| +(which can, however, also be used together with any other package that globally +changes category codes). What it does is to reset the category codes at the +beginning of every |{tikzpicture}| and to restore them at the beginning of +every node. In almost all cases, this is exactly what you would expect and +need, so I recommend to always load this library by saying +|\usetikzlibrary{babel}|. For details on what, exactly, happens with the +category codes, see Section~\ref{section-library-babel}. \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. +``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 -|backgrounds|. This package is documented in -Section~\ref{section-tikz-backgrounds}. +Since backgrounds are often not needed at all, the definition of styles for +adding backgrounds has been put in the library package |backgrounds|. 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. +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. -\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 - environment, that is, any clipping done inside the environment - ``ends'' at its end. +\subsubsection{The Scope Environment} +\begin{environment}{{scope}\opt{\meta{animations spec}}\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}[ultra thick] \begin{scope}[red] @@ -313,50 +303,61 @@ chance of doing anything wrong. \end{tikzpicture} \end{codeexample} - The following style influences scopes: - \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{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. - \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{key} + \begin{key}{/tikz/name=\meta{scope name}} + Assigns a name to a scope reference in animations. The name is a + ``high-level'' name that drivers do not see, so you can use spaces, + number, letters, in a name, but you should \emph{not} use any + punctuation like a dot, a comma, or a colon. + \end{key} + + The following style influences scopes: + % + \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{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. + \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{key} \end{environment} -\begin{plainenvironment}{{scope}\opt{\oarg{options}}} - Plain \TeX\ version of the environment. +\begin{plainenvironment}{{scope}\opt{\meta{animations spec}}\opt{\oarg{options}}} + Plain \TeX\ version of the environment. \end{plainenvironment} -\begin{contextenvironment}{{scope}\opt{\oarg{options}}} - Con\TeX t version of the environment. +\begin{contextenvironment}{{scope}\opt{\meta{animations spec}}\opt{\oarg{options}}} + Con\TeX t version of the environment. \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. + 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: +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] @@ -374,68 +375,67 @@ square brackets: \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. +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. +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. \subsubsection{Single Command Scopes} -In some situations it is useful to create a scope for a single -command. For instance, when you wish to use algorithm graph drawing -in order to layout a tree, the path of the tree needs to be surrounded -by a scope whose only purpose is to take a key that selects a layout -for the scope. Similarly, in order to put something on a background -layer, a scope needs to be created. In such cases, where it will -cumbersome to create a |\begin{scope}| and |\end{scope}| pair just for -a single command, the |\scoped| command may be useful: - -\begin{command}{\scoped\opt{\oarg{options}}\meta{path command}} - This command works like |\tikz|, only you can use it inside a - |{tikzpicture}|. It will take the following \meta{path command} and - put it inside a |{scope}| with the \meta{options} set. The - \meta{path command} may either be a single command ended by a - semicolon or it may contain multiple commands, but then they must be - surrounded by curly braces. - \begin{codeexample}[] +In some situations it is useful to create a scope for a single command. For +instance, when you wish to use algorithm graph drawing in order to layout a +tree, the path of the tree needs to be surrounded by a scope whose only purpose +is to take a key that selects a layout for the scope. Similarly, in order to +put something on a background layer, a scope needs to be created. In such +cases, where it will cumbersome to create a |\begin{scope}| and |\end{scope}| +pair just for a single command, the |\scoped| command may be useful: + +\begin{command}{\scoped\opt{\meta{animations spec}}\opt{\oarg{options}}\meta{path command}} + This command works like |\tikz|, only you can use it inside a + |{tikzpicture}|. It will take the following \meta{path command} and + put it inside a |{scope}| with the \meta{options} set. The + \meta{path command} may either be a single command ended by a + semicolon or it may contain multiple commands, but then they must be + surrounded by curly braces. + % +\begin{codeexample}[] \begin{tikzpicture} \node [fill=white] at (1,1) {Hello world}; \scoped [on background layer] \draw (0,0) grid (3,2); \end{tikzpicture} - \end{codeexample} +\end{codeexample} + % \end{command} \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 -path. Furthermore, it is possible to create local scopes within a -path simply by using curly braces as in +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. +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 Graphic Options} @@ -443,59 +443,56 @@ the node, not to the surrounding path. \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. +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. + 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 -``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 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. +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 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); @@ -503,21 +500,23 @@ lines. \end{tikzpicture} \end{codeexample} -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: +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} -The meaning of the curious |/.style| is the following: ``The key -|my style| should not be used here but, rather, be defined. So, set up -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.'' +The meaning of the curious |/.style| is the following: ``The key |my style| +should not be used here but, rather, be defined. So, set up 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.'' -Returning to the help lines example, suppose we prefer blue help -lines. This could be achieved as follows: +Returning to the help lines example, suppose we prefer blue help lines. This +could be achieved as follows: +% \begin{codeexample}[] \begin{tikzpicture}[help lines/.style={blue!50,very thin}] \draw (0,0) grid +(2,2); @@ -525,9 +524,10 @@ lines. This could be achieved as follows: \end{tikzpicture} \end{codeexample} -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. +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}[] \tikzset{help lines/.style={blue!50,very thin}} % ... @@ -537,28 +537,29 @@ used in different pictures. In this case, we have to use the \end{tikzpicture} \end{codeexample} -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|: +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 parameterized. 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. - +|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 parameterized. 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}[outline/.style={draw=#1,thick,fill=#1!50}] \node [outline=red] at (0,1) {red}; @@ -566,9 +567,9 @@ shows how this can be used. \end{tikzpicture} \end{codeexample} -For parameterized styles you can also set a \emph{default} value using -the |/.default| handler: - +For parameterized 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] |