diff options
author | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
commit | 22536bb2b5257046d271b1eaa11b4a275d5ec041 (patch) | |
tree | 2500eaf5c26b11e00ebd33a64fccfa332cd5a66c /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-pics.tex | |
parent | cf794f0e2db6857972a9d48d4466a4f03a7057a0 (diff) |
pgf (5jan19)
git-svn-id: svn://tug.org/texlive/trunk@49607 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-pics.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-pics.tex | 636 |
1 files changed, 336 insertions, 300 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-pics.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-pics.tex index b4ba727c1d0..c18b7a61766 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-pics.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-pics.tex @@ -7,28 +7,27 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. -\section{Pics: Small Pictures on Paths} +\section{Pics: Small Pictures on Paths} \label{section-pics} \subsection{Overview} -A ``pic'' is a ``short picture'' (hence the short name\dots) that can -be inserted anywhere in \tikzname\ picture where you could also insert -a node. Similarly to nodes, pics have a ``shape'' (called \emph{type} -to avoid confusion) that someone has defined. Each time a pic of a -specified type is used, the type's code is executed, resulting in some -drawings to be added to the current picture. The syntax for adding -nodes and adding pics to a picture are also very similar. The core -difference is that pics are typically more complex than nodes and may -consist of a whole bunch of nodes themselves together with complex -paths joining them. - -As a very simple example, suppose we want to define a pic type -|seagull| that just draw ``two bumps.'' The code for this definition -is quite easy: +A ``pic'' is a ``short picture'' (hence the short name\dots) that can be +inserted anywhere in \tikzname\ picture where you could also insert a node. +Similarly to nodes, pics have a ``shape'' (called \emph{type} to avoid +confusion) that someone has defined. Each time a pic of a specified type is +used, the type's code is executed, resulting in some drawings to be added to +the current picture. The syntax for adding nodes and adding pics to a picture +are also very similar. The core difference is that pics are typically more +complex than nodes and may consist of a whole bunch of nodes themselves +together with complex paths joining them. + +As a very simple example, suppose we want to define a pic type |seagull| that +just draw ``two bumps''. The code for this definition is quite easy: +% \begin{codeexample}[code only] -\tikzset{ +\tikzset{ seagull/.pic={ % Code for a "seagull". Do you see it?... \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); @@ -36,13 +35,12 @@ is quite easy: } \end{codeexample} -The first line just tells \TeX\ that you set some \tikzname\ options -for the current scope (which is the whole document); you could put -|seagull/.pic=...| anywhere else where \tikzname\ options are allowed -(which is just about anywhere). We have now defined a |seagull| pic -type and can use it as follows: - -\tikzset{ +The first line just tells \TeX\ that you set some \tikzname\ options for the +current scope (which is the whole document); you could put |seagull/.pic=...| +anywhere else where \tikzname\ options are allowed (which is just about +anywhere). We have now defined a |seagull| pic type and can use it as follows: +% +\tikzset{ seagull/.pic={ % Code for a "seagull". Do you see it?... \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); @@ -57,91 +55,94 @@ type and can use it as follows: -- (2,1) pic [red] {seagull}; \end{codeexample} -As can be see, defining new types of pics is much easier than defining -new shapes for nodes; but see Section~\ref{section-new-pic-types} -for the fine details. - -Since defining new pics types is easier than defining new node shapes -and since using pics is as easy as using nodes, why should you use -nodes at all? There are chiefly two reasons: +As can be see, defining new types of pics is much easier than defining new +shapes for nodes; but see Section~\ref{section-new-pic-types} for the fine +details. +Since defining new pics types is easier than defining new node shapes and since +using pics is as easy as using nodes, why should you use nodes at all? There +are chiefly two reasons: +% \begin{enumerate} -\item Unlike nodes, pics cannot be referenced later on. You \emph{can} - reference nodes that are inside a pic, but not ``the pic itself.'' - In particular, you cannot draw lines between pics the way you - can draw them between nodes. In general, whenever it makes sense - that some drawing could conceivably be connected to other - node-like-things, then a node is better than a pic. -\item If pics are used to emulate the full power of a node (which is - possible, in principle), they will be slower to construct and take - up more memory than a node achieving the same effect. + \item Unlike nodes, pics cannot be referenced later on. You \emph{can} + reference nodes that are inside a pic, but not ``the pic itself''. In + particular, you cannot draw lines between pics the way you can draw + them between nodes. In general, whenever it makes sense that some + drawing could conceivably be connected to other node-like-things, then + a node is better than a pic. + \item If pics are used to emulate the full power of a node (which is + possible, in principle), they will be slower to construct and take up + more memory than a node achieving the same effect. \end{enumerate} -Despite these drawbacks, pics are an excellent choice for creating -highly configurable reusable pieces of drawings that can be inserted -into larger contexts. +Despite these drawbacks, pics are an excellent choice for creating highly +configurable reusable pieces of drawings that can be inserted into larger +contexts. \subsection{The Pic Syntax} \begin{command}{\pic} - Inside |{tikzpicture}| this is an abbreviation for |\path pic|. + Inside |{tikzpicture}| this is an abbreviation for |\path pic|. \end{command} -The syntax for adding a pic to a picture is very similar to the syntax -used for nodes (indeed, internally the same parser code is used). The -main difference is that instead of a node contents you provide the -picture's type between the braces: - -\begin{pathoperation}{pic}{\opt{\meta{foreach statements}}% - \opt{|[|\meta{options}|]|}\opt{|(|\meta{prefix}|)|}% - \opt{|at(|\meta{coordinate}|)|}\opt{\marg{pic type}}} - - Adds a pic to the current \tikzname\ picture of the specified - \meta{pic type}. The effect is, basically, that some code associated - with the \meta{pic type} is executed (how this works, exactly, is explained - later). This code can consist of arbitrary \tikzname\ code. As for - nodes, the current path will not be modified by this path command, - all drawings produced by the code are ``external'' to the path the - same way neither a node nor its border are part of the path on which - they are specified. - - Just like the |node| command, this path operation is somewhat - complex and we go over it step by step. - - \medskip - \textbf{Order of the parts of the specification.} - Just like for nodes, everything between ``|pic|'' and the opening - brace of the \meta{pic type} is optional and can be given in any - order. If there are \meta{foreach statements}, they must come - first, directly following ``|pic|.'' As for nodes, the ``end'' of - the pic specification is normally detected by the presence of the - opening brace. You can, however, use the |pic type| - option to specify the pic type as an option. - - \begin{key}{/tikz/pic type=\meta{pic type}} - This key sets the pic type of the current~|pic|. When this option - is used inside an option block of a |pic|, the parsing of the - |pic| ends immediately and no pic type in braces is expected. (In - other words, this option behaves exactly like the |node contents| - option and, indeed, the two are interchangeable.) +The syntax for adding a pic to a picture is very similar to the syntax used for +nodes (indeed, internally the same parser code is used). The main difference is +that instead of a node contents you provide the picture's type between the +braces: + +\begin{pathoperation}{pic}{ + \opt{\meta{foreach statements}} + \opt{|[|\meta{options}|]|} + \opt{|(|\meta{prefix}|)|} + \opt{|at(|\meta{coordinate}|)|} + \opt{|:|\meta{animation attribute}|=|\marg{options}} + \opt{\marg{pic type}}% +} + Adds a pic to the current \tikzname\ picture of the specified \meta{pic + type}. The effect is, basically, that some code associated with the + \meta{pic type} is executed (how this works, exactly, is explained later). + This code can consist of arbitrary \tikzname\ code. As for nodes, the + current path will not be modified by this path command, all drawings + produced by the code are ``external'' to the path the same way neither a + node nor its border are part of the path on which they are specified. + + Just like the |node| command, this path operation is somewhat complex and + we go over it step by step. + + \medskip + \textbf{Order of the parts of the specification.} + Just like for nodes, everything between ``|pic|'' and the opening brace of + the \meta{pic type} is optional and can be given in any order. If there are + \meta{foreach statements}, they must come first, directly following + ``|pic|''. As for nodes, the ``end'' of the pic specification is normally + detected by the presence of the opening brace. You can, however, use the + |pic type| option to specify the pic type as an option. + + \begin{key}{/tikz/pic type=\meta{pic type}} + This key sets the pic type of the current~|pic|. When this option is + used inside an option block of a |pic|, the parsing of the |pic| ends + immediately and no pic type in braces is expected. (In other words, + this option behaves exactly like the |node contents| option and, + indeed, the two are interchangeable.) + % \begin{codeexample}[] \tikz { \path (0,0) pic [pic type = seagull] (1,0) pic {seagull}; } \end{codeexample} - \end{key} - - \medskip - \textbf{The location of a pic.} - Just like nodes, pics are placed at the last position mentioned on - the path or, when |at| is used, at a specified position. ``Placing'' - a pic somewhere actually means that the coordinate system is - translated (shifted) to this last position. This means that inside - of the pic type's code any mentioning of the origin refers to the - last position used on the path or to the specified |at|. - + \end{key} + + \medskip + \textbf{The location of a pic.} + Just like nodes, pics are placed at the last position mentioned on the path + or, when |at| is used, at a specified position. ``Placing'' a pic somewhere + actually means that the coordinate system is translated (shifted) to this + last position. This means that inside of the pic type's code any mentioning + of the origin refers to the last position used on the path or to the + specified |at|. + % \begin{codeexample}[] \tikz { % different ways of placing pics \draw [help lines] (0,0) grid (3,2); @@ -151,88 +152,88 @@ picture's type between the braces: } \end{codeexample} - As for nodes, except for the described shifting, the coordinate - system of a pic is reset prior to executing the pic type's - code. This can be changed using the |transform shape| option, which - has the same effect as for nodes: The ``outer'' transformation gets - applied to the node: + As for nodes, except for the described shifting, the coordinate system of a + pic is reset prior to executing the pic type's code. This can be changed + using the |transform shape| option, which has the same effect as for nodes: + The ``outer'' transformation gets applied to the node: + % \begin{codeexample}[] -\tikz [scale=2] { +\tikz [scale=2] { \pic at (0,0) {seagull}; \pic at (1,0) [transform shape] {seagull}; } \end{codeexample} - When the \meta{options} contain transformation commands like |scale| - or |rotate|, these transformations always apply to the pic: + When the \meta{options} contain transformation commands like |scale| or + |rotate|, these transformations always apply to the pic: + % \begin{codeexample}[] -\tikz [rotate=30] { +\tikz [rotate=30] { \pic at (0,0) {seagull}; \pic at (1,0) [rotate=90] {seagull}; } \end{codeexample} - Just like nodes, pics can also be positioned implicitly and, - somewhat unsurprisingly, the same rules concerning positioning and - sloping apply: + Just like nodes, pics can also be positioned implicitly and, somewhat + unsurprisingly, the same rules concerning positioning and sloping apply: + % \begin{codeexample}[] \tikz \draw - (0,0) to [bend left] - pic [near start] {seagull} + (0,0) to [bend left] + pic [near start] {seagull} pic {seagull} pic [sloped, near end] {seagull} (4,0); \end{codeexample} - - \medskip - \textbf{The options of a node.} - As always, any given \meta{options} apply only to the pic and have - no effect outside. As for nodes, most ``outside'' options also apply - to the pics, but not the ``action'' options like |draw| or - |fill|. These must be given in the \meta{options} of the pic. - - \medskip - \textbf{The code of a pic.} - As stated earlier, the main job of a pic is to execute some code in - a scope that is shifted according to the last point on the path or - to the |at| position specified in the pic. It was also claimed that - this code is specified by the \meta{pic type}. However, this - specification is somewhat indirect. What really happens is the - following: When a |pic| is encountered, the current path is - suspended and a new internal scope is started. The \meta{options} - are executed and also the \meta{pic type} (as explained - in a moment). After all this is done, the code stored in the following key - gets executed: - - \begin{key}{/tikz/pics/code=\meta{code}} - This key stores the \meta{code} that should be drawn in the - current pic. Normally, setting this key is done by the \meta{pic - type}, but you can also set it in the \meta{options} and leave - the \meta{pic type} empty: + + \medskip + \textbf{The options of a node.} + As always, any given \meta{options} apply only to the pic and have no + effect outside. As for nodes, most ``outside'' options also apply to the + pics, but not the ``action'' options like |draw| or |fill|. These must be + given in the \meta{options} of the pic. + + \medskip + \textbf{The code of a pic.} + As stated earlier, the main job of a pic is to execute some code in a scope + that is shifted according to the last point on the path or to the |at| + position specified in the pic. It was also claimed that this code is + specified by the \meta{pic type}. However, this specification is somewhat + indirect. What really happens is the following: When a |pic| is + encountered, the current path is suspended and a new internal scope is + started. The \meta{options} are executed and also the \meta{pic type} (as + explained in a moment). After all this is done, the code stored in the + following key gets executed: + + \begin{key}{/tikz/pics/code=\meta{code}} + This key stores the \meta{code} that should be drawn in the current + pic. Normally, setting this key is done by the \meta{pic type}, but you + can also set it in the \meta{options} and leave the \meta{pic type} + empty: + % \begin{codeexample}[] \tikz \pic [pics/code={\draw (-3mm,0) to[bend left] (0,0) to[bend left] (3mm,0);}] {}; % no pic type specified \end{codeexample} - \end{key} - - Now, how does the \meta{pic type} set |pics/code|? It turns out that - the \meta{pic type} is actually just a list of keys that are - executed with the prefix |/tikz/pics/|. In the above examples, this - ``list of keys'' just consisted of the single key ``|seagull|'' that - did not take any arguments, but, in principle, you could provide any - arbitrary text understood by |\pgfkeys| here. This means that when - we write |pic{seagull}|, \tikzname\ will execute the key - |/tikz/pics/seagull|. It turns out, see - Section~\ref{section-new-pic-types}, that this key is just a style - set to |code={\draw(-3mm,0)...;}|. Thus, |pic{seagull}| will cause - the |pics/code| key to be set to the text needed to draw the - seagull. - - Indeed, you can also use the \meta{pic type} simply to set the - |code| of the pic. This is useful for cases when you have some code - that you ``just want to execute, but do not want to define a new pic - type.'' Here is a typical example where we use pics to add some - markings to a path: + \end{key} + + Now, how does the \meta{pic type} set |pics/code|? It turns out that the + \meta{pic type} is actually just a list of keys that are executed with the + prefix |/tikz/pics/|. In the above examples, this ``list of keys'' just + consisted of the single key ``|seagull|'' that did not take any arguments, + but, in principle, you could provide any arbitrary text understood by + |\pgfkeys| here. This means that when we write |pic{seagull}|, \tikzname\ + will execute the key |/tikz/pics/seagull|. It turns out, see + Section~\ref{section-new-pic-types}, that this key is just a style set to + |code={\draw(-3mm,0)...;}|. Thus, |pic{seagull}| will cause the |pics/code| + key to be set to the text needed to draw the + seagull. + + Indeed, you can also use the \meta{pic type} simply to set the |code| of + the pic. This is useful for cases when you have some code that you ``just + want to execute, but do not want to define a new pic type''. Here is a + typical example where we use pics to add some markings to a path: + % \begin{codeexample}[] \tikz \draw (0,0) .. controls(1,0) and (2,1) .. (3,1) foreach \t in {0, 0.1, ..., 1} { @@ -240,21 +241,22 @@ picture's type between the braces: }; \end{codeexample} - - In our seagull example, we always explicitly used |\draw| to draw - the seagull. This implies that when a user writes something - |pic[fill]{seagull}| in the hope of having a ``filled'' seagull, - nothing special will happen: The |\draw| inside the pic explicitly - states that the path should be drawn, not filled, and the fact that - in the surrounding scope the |fill| option is set has no effect. - The following key can be used to change this: - \begin{key}{/tikz/pic actions} - This key is a style that can be used (only) inside the code of a - pic. There, it will set the ``action'' keys set inside the - \meta{options} of the pic (``actions'' are drawing, filling, - shading, and clipping or any combination thereof). - - To see how this key works, let us define the following pic: + In our seagull example, we always explicitly used |\draw| to draw the + seagull. This implies that when a user writes something + |pic[fill]{seagull}| in the hope of having a ``filled'' seagull, nothing + special will happen: The |\draw| inside the pic explicitly states that the + path should be drawn, not filled, and the fact that in the surrounding + scope the |fill| option is set has no effect. The following key can be used + to change this: + % + \begin{key}{/tikz/pic actions} + This key is a style that can be used (only) inside the code of a pic. + There, it will set the ``action'' keys set inside the \meta{options} of + the pic (``actions'' are drawing, filling, shading, and clipping or any + combination thereof). + + To see how this key works, let us define the following pic: + % \begin{codeexample}[code only] \tikzset{ my pic/.pic = { @@ -263,9 +265,11 @@ picture's type between the braces: } } \end{codeexample} - In the code, whether or not the circle gets drawn/filled/shaded - depends on which options where given to the |pic| command when it - is used. In contrast, the rectangle will always (just) be drawn. + % + In the code, whether or not the circle gets drawn/filled/shaded + depends on which options where given to the |pic| command when it + is used. In contrast, the rectangle will always (just) be drawn. + % \tikzset{ my pic/.pic = { \path [pic actions] (0,0) circle[radius=3mm]; @@ -280,19 +284,19 @@ picture's type between the braces: \tikz \pic [draw, shading=ball] {my pic}; \space \tikz \pic [fill=red!50] {my pic}; \end{codeexample} - \end{key} - - \medskip - \textbf{Code executed behind or in front of the path.} - As for nodes, a pic can be ``behind'' the current path or ``in front - of it'' and, just as for nodes, the two options |behind path| and - |in front of path| are used to specify which is meant. In detail, if - |node| and |pic| are both used repeatedly on a path, in the - resulting picture we first see all nodes and pics with the - |behind path| option set in the order they appear on the path (nodes - and pics are interchangeable in this regard), then comes the path, - and then come all nodes and pics that are in front of the path in - the order they appeared. + \end{key} + + \medskip + \textbf{Code executed behind or in front of the path.} + As for nodes, a pic can be ``behind'' the current path or ``in front of + it'' and, just as for nodes, the two options |behind path| and + |in front of path| are used to specify which is meant. In detail, if |node| + and |pic| are both used repeatedly on a path, in the resulting picture we + first see all nodes and pics with the |behind path| option set in the order + they appear on the path (nodes and pics are interchangeable in this + regard), then comes the path, and then come all nodes and pics that are in + front of the path in the order they appeared. + % \begin{codeexample}[] \tikz \fill [fill=blue!20] (1,1) @@ -301,87 +305,91 @@ picture's type between the braces: -- (3,1) pic [rotate=30] {seagull} -- (2,1) pic [red, behind path] {seagull}; \end{codeexample} - In contrast to nodes, a pic need not only be completely behind - the path or in front of the path as specified by the user. Instead, - a pic type may also specify that a certain part of the drawing - should always be behind the path and it may specify that a certain - other part should always be before the path. For this, the values of - the following keys are relevant: - - \begin{key}{/tikz/pics/foreground code=\meta{code}} - This key stores \meta{code} that will always be drawn in front of - the current path, even when |behind path| is used. If - |behind path| is not used and |code| is (also) set, the code of - |code| is - drawn first, following by the foreground \meta{code}. - \end{key} - - \begin{key}{/tikz/pics/background code=\meta{code}} - Like |foreground code|, only that the \meta{code} is always put - behind the path, never in front of it. - \end{key} - - \medskip - \textbf{The foreach statement for pics.} - As for nodes, a pic specification may start with |foreach|. The - effect and semantics are the same as for nodes. + % + In contrast to nodes, a pic need not only be completely behind the path or + in front of the path as specified by the user. Instead, a pic type may also + specify that a certain part of the drawing should always be behind the path + and it may specify that a certain other part should always be before the + path. For this, the values of the following keys are relevant: + + \begin{key}{/tikz/pics/foreground code=\meta{code}} + This key stores \meta{code} that will always be drawn in front of the + current path, even when |behind path| is used. If |behind path| is not + used and |code| is (also) set, the code of |code| is drawn first, + following by the foreground \meta{code}. + \end{key} + + \begin{key}{/tikz/pics/background code=\meta{code}} + Like |foreground code|, only that the \meta{code} is always put behind + the path, except when the |behind path| option is applied to the pic, + then the background code is drawn in front of the ``behind path'' code. + \end{key} + + \medskip + \textbf{The foreach statement for pics.} + As for nodes, a pic specification may start with |foreach|. The effect and + semantics are the same as for nodes. + % \begin{codeexample}[] \tikz \pic foreach \x in {1,2,3} at (\x,0) {seagull}; \end{codeexample} - \medskip - \textbf{Styles for pics.} - The following styles influence how nodes are rendered: - \begin{stylekey}{/tikz/every pic (initially \normalfont empty)} - This style is installed at the beginning of every pic. + \medskip + \textbf{Styles for pics.} + The following styles influence how nodes are rendered: + % + \begin{stylekey}{/tikz/every pic (initially \normalfont empty)} + This style is installed at the beginning of every pic. + % \begin{codeexample}[] \begin{tikzpicture}[every node/.style={draw}] \draw (0,0) node {A} -- (1,1) node {B}; \end{tikzpicture} \end{codeexample} - \end{stylekey} - - - \medskip - \textbf{Name scopes.} - You can specify a \meta{name} for a pic using the key - |name=|\meta{name} or by giving the name in parenthesis inside the - pic's specification. The effect of this is, for once, quite - different from what happens for nodes: All that happens is that - |name prefix| is set to \meta{name} at the beginning of the pic. - - The |name prefix| key was already introduced in the description of - the |node| command: It allows you to set some text that is prefixed - to all nodes in a scope. For pics this makes particular sense: All - nodes defined by a pic's code can be referenced from outside the pic - with the prefix provided. - - To see how this works, let us add some nodes to the code of the - seagull: + \end{stylekey} + + \medskip + \textbf{Name scopes.} + You can specify a \meta{name} for a pic using the key |name=|\meta{name} or + by giving the name in parenthesis inside the pic's specification. The + effect of this is, for once, quite different from what happens for nodes: + All that happens is that |name prefix| is set to \meta{name} at the + beginning of the pic. + + The |name prefix| key was already introduced in the description of the + |node| command: It allows you to set some text that is prefixed to all + nodes in a scope. For pics this makes particular sense: All nodes defined + by a pic's code can be referenced from outside the pic with the prefix + provided. + + To see how this works, let us add some nodes to the code of the seagull: + % \begin{codeexample}[code only] -\tikzset{ +\tikzset{ seagull/.pic={ % Code for a "seagull". Do you see it?... \coordinate (-left wing) at (-3mm,0); \coordinate (-head) at (0,0); \coordinate (-right wing) at (3mm,0); - + \draw (-left wing) to [bend left] (0,0) (-head) to [bend left] (-right wing); } } \end{codeexample} -\tikzset{ + % +\tikzset{ seagull/.pic={ % Code for a "seagull". Do you see it?... \coordinate (-left wing) at (-3mm,0); \coordinate (-head) at (0,0); \coordinate (-right wing) at (3mm,0); - + \draw (-left wing) to [bend left] (0,0) (-head) to [bend left] (-right wing); } } - Now, we can use it as follows: + Now, we can use it as follows: + % \begin{codeexample}[code only] \tikz { \pic (Emma) {seagull}; @@ -391,63 +399,90 @@ picture's type between the braces: } \end{codeexample} - Sometimes, you may also wish your pic to access nodes outside the - pic (typically, because they are given as parameters). In this case, - the name prefix gets in the way since the nodes outside the picture - do not have this prefix. The trick is to locally reset the name - prefix to the value it had outside the picture, which is achieved - using the following style: - - \begin{key}{/tikz/name prefix ..} - This key is available only inside the code of a pic. There, it - (locally) changes the name prefix to the value it had outside the - pic. This allows you to access nodes outside the current pic. - \end{key} - + Sometimes, you may also wish your pic to access nodes outside the pic + (typically, because they are given as parameters). In this case, the name + prefix gets in the way since the nodes outside the picture do not have this + prefix. The trick is to locally reset the name prefix to the value it had + outside the picture, which is achieved using the following style: + + \begin{key}{/tikz/name prefix ..} + This key is available only inside the code of a pic. There, it + (locally) changes the name prefix to the value it had outside the pic. + This allows you to access nodes outside the current pic. + \end{key} + + \medskip + \textbf{Animations for pics.} + Just as for nodes, you can use the attribute--colon syntax to add an + animation to a pic: + % +\begin{codeexample}[animation list={0.5,1,1.5,2}] +\tikz { + \pic :rotate={0s="0", 20s="90"} {seagull}; + \pic at (1.5,1.5) {seagull}; +} +\end{codeexample} + % + Naturally, you can also use animations in the code of a picture: + % +\begin{codeexample}[animation list={0.5,1,1.5,2},width=3cm] +\begin{tikzpicture} [flapping seagull/.pic={ + \draw (0,0) :path={ + 0s= {"{(180:3mm) to [bend left] (0,0) to [bend left] (0:3mm)}"=base}, + 1s= "{(160:3mm) to [bend left] (0,0) to [bend left] (20:3mm)}", + 2s= "{(180:3mm) to [bend left] (0,0) to [bend left] (0:3mm)}", + repeats }; + }] + \pic :rotate={0s="0", 20s="90"} {flapping seagull}; + \pic at (1.5,1.5) {flapping seagull}; +\end{tikzpicture} +\end{codeexample} + % \end{pathoperation} - There are two general purpose keys that pics may find useful: \begin{key}{/tikz/pic text=\meta{text}} - This macro stores the \meta{text} in the macro |\tikzpictext|, which - is |\let| to |\relax| by default. Setting the |pic text| to some - value is the ``preferred'' way of communicating a (single) piece of - text that should become part of a pic (typically of a node). In - particular, the |quotes| library maps quoted parameters to this key. + This macro stores the \meta{text} in the macro |\tikzpictext|, which is + |\let| to |\relax| by default. Setting the |pic text| to some value is the + ``preferred'' way of communicating a (single) piece of text that should + become part of a pic (typically of a node). In particular, the |quotes| + library maps quoted parameters to this key. \end{key} \begin{key}{/tikz/pic text options=\meta{options}} - This macro stores the \meta{options} in the macro - |\tikzpictextoptions|, which is |\let| to the empty string by - default. The |quotes| library maps options for quoted parameters to - this key. + This macro stores the \meta{options} in the macro |\tikzpictextoptions|, + which is |\let| to the empty string by default. The |quotes| library maps + options for quoted parameters to this key. \end{key} - \subsubsection{The Quotes Syntax} \label{section-pic-quotes} -When you load the |quotes| library, you can use the ``quotes syntax'' -inside the options of a pic. Recall that for nodes this syntax is used -to add a label to a node. For pics, the quotes syntax is used to set -the |pic text| key. Whether or not the pic type's code takes this key -into consideration is, however, up to the key. +When you load the |quotes| library, you can use the ``quotes syntax'' inside +the options of a pic. Recall that for nodes this syntax is used to add a label +to a node. For pics, the quotes syntax is used to set the |pic text| key. +Whether or not the pic type's code takes this key into consideration is, +however, up to the key. -In detail, when the |quotes| library is loaded, each time a key--value -pair in a list of options passed to an |pic| starts with |"|, the -key--value pair must actually be a string of the following form: +In detail, when the |quotes| library is loaded, each time a key--value pair in +a list of options passed to an |pic| starts with |"|, the key--value pair must +actually be a string of the following form: +% \begin{quote} - |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} + |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} \end{quote} +% This string is transformed into the following: +% \begin{quote} - |every pic quotes/.try,pic text=|\meta{text}|, pic text options={|\meta{options}|}| + |every pic quotes/.try,pic text=|\meta{text}|, pic text options={|\meta{options}|}| \end{quote} -As example of a pic type that takes these values into account is the -|angle| pic type: +As example of a pic type that takes these values into account is the |angle| +pic type: +% \begin{codeexample}[] \tikz \draw (3,0) coordinate (A) -- (0,1) coordinate (B) @@ -455,20 +490,23 @@ As example of a pic type that takes these values into account is the pic [draw, "$\alpha$"] {angle}; \end{codeexample} -As described in Section~\ref{section-label-quotes}, the apostrophe -becomes part of the \meta{options}, when present. As can be seen -above, the following style is executed: +As described in Section~\ref{section-label-quotes}, the apostrophe becomes part +of the \meta{options}, when present. As can be seen above, the following style +is executed: +% \begin{stylekey}{/tikz/every pic quotes (initially \normalfont empty)} \end{stylekey} + \subsection{Defining New Pic Types} \label{section-new-pic-types} -As explained in the description of the |pic| command, in order to -define a new pic type you need to +As explained in the description of the |pic| command, in order to define a new +pic type you need to +% \begin{enumerate} -\item define a key with the path prefix |/tikz/pics| that -\item sets the key |/tikz/pics/code| to the code of the pic. + \item define a key with the path prefix |/tikz/pics| that + \item sets the key |/tikz/pics/code| to the code of the pic. \end{enumerate} It turns out that this is easy enough to achieve using styles: @@ -476,7 +514,7 @@ It turns out that this is easy enough to achieve using styles: \begin{codeexample}[code only] \tikzset{ pics/seagull/.style ={ - % Ok, this is the key that should, when + % Ok, this is the key that should, when % executed, set the code key: code = { % \draw (...) ... ; @@ -485,10 +523,9 @@ It turns out that this is easy enough to achieve using styles: } \end{codeexample} -Even though the above pattern is easy enough, there is a special -so-called key handler that allows us to write even simpler code, -namely: - +Even though the above pattern is easy enough, there is a special so-called key +handler that allows us to write even simpler code, namely: +% \begin{codeexample}[code only] \tikzset{ seagull/.pic = { @@ -498,28 +535,27 @@ namely: \end{codeexample} \begin{handler}{{.pic}|=|\meta{some code}} - This handler can only be used with a key with the prefix |/tikz/|, - so just should normally use it only as an option to a \tikzname\ - command or to the |\tikzset| command. It takes the \meta{key}'s path - and, inside that path, it replaces |/tikz/| by |/tikz/pics/| (so, - basically, it adds the ``missing'' |pics| part of the path). Then, - it sets up things so that the resulting name to key is a style that - executes |code=some code|. + This handler can only be used with a key with the prefix |/tikz/|, so just + should normally use it only as an option to a \tikzname\ command or to the + |\tikzset| command. It takes the \meta{key}'s path and, inside that path, + it replaces |/tikz/| by |/tikz/pics/| (so, basically, it adds the + ``missing'' |pics| part of the path). Then, it sets up things so that the + resulting name to key is a style that executes |code=some code|. \end{handler} -In almost all cases, the |.pic| key handler will suffice to setup -keys. However, there are cases where you really need to use the first -version using |.style| and |code=|: +In almost all cases, the |.pic| key handler will suffice to setup keys. +However, there are cases where you really need to use the first version using +|.style| and |code=|: +% \begin{itemize} -\item Whenever your pic type needs to set the foreground or the - background code. -\item In case of complicated arguments given to the keys. + \item Whenever your pic type needs to set the foreground or the background + code. + \item In case of complicated arguments given to the keys. \end{itemize} -As an example, let us define a simple pic that draws a filled circle -behind the path. Furthermore, we make the circle's radius a parameter -of the pic: - +As an example, let us define a simple pic that draws a filled circle behind the +path. Furthermore, we make the circle's radius a parameter of the pic: +% \begin{codeexample}[] \tikzset{ pics/my circle/.style = { |