diff options
author | Norbert Preining <norbert@preining.info> | 2022-12-05 03:03:23 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2022-12-05 03:03:23 +0000 |
commit | 673717f7c662dd135f63b61c1da1ecd59bcdbe90 (patch) | |
tree | 9fe13f30ece99ab02f375cefab300a65b069560c /support/digestif/data/pgf.tags | |
parent | b153d9b098596910fb2be9311f13c4415233c2a2 (diff) |
CTAN sync 202212050303
Diffstat (limited to 'support/digestif/data/pgf.tags')
-rw-r--r-- | support/digestif/data/pgf.tags | 20068 |
1 files changed, 20068 insertions, 0 deletions
diff --git a/support/digestif/data/pgf.tags b/support/digestif/data/pgf.tags new file mode 100644 index 0000000000..24bdeeec27 --- /dev/null +++ b/support/digestif/data/pgf.tags @@ -0,0 +1,20068 @@ +-- Copyright 2007-2013 Till Tantau +-- Copyright 2022 Augusto Stoffel, Jens Schneider +-- SPDX-License-Identifier: GFDL-1.2-or-later or LPPL-1.3c+ +-- +-- Adapted from the PGF manual, version 3.1.9a, which can be found at +-- https://github.com/pgf-tikz/pgf/. +ctan_package = "pgf" +documentation = {{summary = "PGF Manual", uri = "texmf:doc/generic/pgf/pgfmanual.pdf"}} +commands = { + beginpgfgraphicnamed = { + arguments = {{meta = "file name prefix"}}, + details = [[ +This command indicates that everything up to the next call of +`\endpgfgraphicnamed` is part of a graphic that should be placed in a +file named ⟨file name prefix⟩`.`⟨suffix⟩, where the ⟨suffix⟩ depends on +your backend driver. Typically, ⟨suffix⟩ will be `dvi` or `pdf`. + +Here is a typical example of how this command is used: + + % In file main.tex: + ... + As we see in Figure~\ref{fig1}, the world is flat. + \begin{figure} + \beginpgfgraphicnamed{graphic-of-flat-world} + \begin{tikzpicture} + \fill (0,0) circle (1cm); + \end{tikzpicture} + \endpgfgraphicnamed + \caption{The flat world.} + \label{fig1} + \end{figure} + +Each graphic to be externalized should have a unique name. Note that +this name will be used as the name of a file in the file system, so it +should not contain any funny characters. + +This command can have three different effects: + +1. The easiest situation arises if there does not yet exist a graphic + file called ⟨file name prefix⟩`.`⟨suffix⟩, where the ⟨suffix⟩ is one + of the suffixes understood by your current backend driver (so `pdf` + or `jpg` if you use `pdftex`, `eps` if you use `dvips`, and so on). + In this case, both this command and the `\endpgfgraphicnamed` + command simply have no effect. + +2. A more complex situation arises when a graphic file named ⟨file name + prefix⟩`.`⟨suffix⟩ *does* exist. In this case, this graphic file is + included using the `\includegraphics` command [1]. Furthermore, the + text between `\beginpgfgraphicnamed` and `\endpgfgraphicnamed` is + ignored. + + When the text is "ignored", what actually happens is that all text + up to the next occurrence of `\endpgfgraphicnamed` is thrown away + without any macro expansion. This means, in particular, that (a) you + cannot put `\endpgfgraphicnamed` inside a macro and (b) the macros + used in the graphics need not be defined at all when the graphic + file is included. + +3. The most complex behavior arises when current the `\jobname` equals + the ⟨file name prefix⟩ and, furthermore, the *real job name* has + been declared. The behavior for this case is explained later. + +Note that the `\beginpgfgraphicnamed` does not really have any effect +until you have generated the graphic files named. Till then, this +command is simply ignored. Also, if you delete the graphics file later +on, the graphics are typeset normally once more. + +[1] Actually, the command key `/pgf/images/include external` is invoked +which calls an appropriate `\includegraphics` command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/beginpgfgraphicnamed" + }, + endpgfgraphicnamed = { + details = [[ +This command just marks the end of the graphic that should be +externalized. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/endpgfgraphicnamed" + }, + ifpgfmathmathunitsdeclared = { + details = [[ +This TeX-if is similar to `\ifpgfmathunitsdeclared`, but it is only set +when the unit `mu` is encountered at least once. In this case, +`\ifpgfmathunitsdeclared` will *also* be set to true. The `scalar` +function has no effect on this TeX-if. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfmathmathunitsdeclared" + }, + ifpgfmathunitsdeclared = { + details = [[ +After a call of `\pgfmathparse` this if will be true exactly if some +unit was encountered in the expression. It is always set globally in +each call. + +Note that *any* "mentioning" of a unit inside an expression will set +this TeX-if to true. In particular, even an expressionlike `2pt/1pt`, +which arguably should be considered "scalar" or "unit-free" will still +have this TeX-if set to true. However, see the `scalar` function for a +way to change this. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfmathunitsdeclared" + }, + ifpgfrememberpicturepositiononpage = { + details = [[ +Determines whether the position of pictures on the page should be +recorded. The value of this TeX-if at the end of a `{pgfpicture}` +environment is important, not the value at the beginning. + +If this option is set to true of a picture, PGF will attempt to record +the position of the picture on the page. (This attempt will fail with +most drivers and when it works, it typically requires two runs of TeX.) +The position is not directly accessible. Rather, the nodes mechanism +will use this position if you access a node from another picture. See +Sections ?? and ?? for more details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfrememberpicturepositiononpage" + }, + ifpgfshadingmodelcmyk = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +test if the `xcolor` color model is `cmyk` *at the time the shading is +created*. This can be used to ensure that the data output in the ⟨type 4 +function⟩ correctly matches the active color model. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfshadingmodelcmyk" + }, + ifpgfshadingmodelgray = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +test if the `xcolor` color model is `gray` *at the time the shading is +created*. This can be used to ensure that the data output in the ⟨type 4 +function⟩ correctly matches the active color model. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfshadingmodelgray" + }, + ifpgfshadingmodelrgb = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +test if the `xcolor` color model is `rgb` *at the time the shading is +created*. This can be used to ensure that the data output in the ⟨type 4 +function⟩ correctly matches the active color model. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfshadingmodelrgb" + }, + ["ifpgfsys@eorule"] = { + details = [[ +Determines whether the even odd rule is used for filling and clipping or +not. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfsys@eorule" + }, + ["ifpgfsys@transparency@group@isolated"] = { + details = [[ +Determines whether a transparency group should be isolated. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfsys@transparency@group@isolated" + }, + ["ifpgfsys@transparency@group@knockout"] = { + details = [[ +Determines whether a transparency group is a knockout group or not. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfsys@transparency@group@knockout" + }, + ["pgf@process"] = { + arguments = {{meta = "code"}}, + details = [[ +Executes the ⟨code⟩ in a scope and then makes `\pgf@x` and `\pgf@y` +global. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgf@process" + }, + ["pgf@protocolsizes"] = { + arguments = {{meta = "x-dimension"}, {meta = "y-dimension"}}, + details = [[ +Updates all of the above dimensions in such a way that the point +specified by the two arguments is inside both bounding boxes. For the +picture's bounding box this updating occurs only if +`\ifpgf@relevantforpicturesize` is true, see below. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgf@protocolsizes" + }, + ["pgf@relevantforpicturesizefalse"] = { + details = [[ +Suppresses updating of the picture's bounding box. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgf@relevantforpicturesizefalse" + }, + ["pgf@relevantforpicturesizetrue"] = { + details = [[ +Causes updating of the picture's bounding box. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgf@relevantforpicturesizetrue" + }, + ["pgf@sys@bp"] = { + arguments = {{meta = "dimension"}}, + details = [[ +Inserts how many multiples of $\frac{1}{72}\mathrm{in}$ the ⟨dimension⟩ +is into the current protocol stream (buffered). + +`\pgf@sys@bp{\pgf@x}` or `\pgf@sys@bp{1cm}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgf@sys@bp" + }, + pgfactualjobname = { + details = [[ +Once `\tikzexternalize` has been called, `\pgfactualjobname` contains +the name of the currently generated output file (which may be `main` or +`main-figure0` or `main-figure1` in our example above). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfactualjobname" + }, + pgfaliasid = { + arguments = {{meta = "alias"}, {meta = "name"}}, + details = [[ +Creates an alias of a name inside the current TeX scope. After calling +this command, you can use ⟨alias⟩ anywhere where you would normally use +⟨name⟩. Note that the binding between ⟨alias⟩ and ⟨name⟩ is not kept +when `\pgfuseid` is used on the ⟨name⟩ (or the ⟨alias⟩). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfaliasid" + }, + pgfaliasimage = { + arguments = {{meta = "new image name"}, {meta = "existing image name"}}, + details = [[ +The `{existing image name}` is "cloned" and the `{new image name}` can +now be used whenever the original image is used. This command is useful +for creating aliases for alternate extensions and for accessing the last +image inserted using `\pgfimage`. + +`\pgfaliasimage{image.!30!white}{image.!25!white}` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfaliasimage" + }, + pgfalternateextension = { + details = [[ +You should redefine this command to install a different alternate +extension. + +`\def\pgfalternateextension{!25!white}` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfalternateextension" + }, + pgfanimateattribute = { + arguments = { + {meta = "attribute"}, + {keys = "$ref:pgf#/keys/pgf", meta = "options"} + }, + details = [[ +Adds an animation of the ⟨attribute⟩ of a future *object* to the current +graphic. Attributes are things like the "fill opacity" or the +transformation matrix or the line width. + +The ⟨options⟩ are keys that configure how the attribute changes over +time. Using the `entry` key multiple times, you specify which value the +chosen attribute should have at different points in time. Unless special +keys are used, "outside" the specified timeline the animation has no +effect: + + \tikz { + \pgfanimateattribute{opacity}{ + whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} } + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } + +Other keys, like `repeats`, allow you to specify how the animation +behaves "as a whole". These keys are documented later in this section. + +**The Attributes** + +In detail, the `\pgfanimateattribute` command opens a TeX-scope, looks +up the *type* values of the specified ⟨attribute⟩ have (if you wish to +animate the `opacity` of an object, the type is "scalar" meaning that +entries must be scalar numbers; when you animate the `fill` attribute, +the type is "color" and values must be colors, and so on), and then +executes the ⟨options⟩ with the path prefix `/pgf/animation`. Finally, +an appropriate system layer command `\pgfsysanimate...` is called to +create the actual animation and the scope is closed. + +The following ⟨attributes⟩ are permissible: + + ------------------------------------------- ----------- + *Attribute* *Type* + `draw`, `fill` color + `line width` dimension + `motion` scalar + `opacity`, `fill opacity`, `draw opacity` scalar + `path` path + `rotate` scalar + `scale` scaling + `softpath` softpath + `translate` point + `view` viewbox + `visible` boolean + `stage` boolean + `xskew`, `yskew` scalar + ------------------------------------------- ----------- + +These attributes are detailed in Sections ?? to ??, but here is a quick +overview: + +- `draw` and `fill` refer to the color used to draw (stroke) and fill + paths in an object, respectively. Typical values for this attribute + are `red` or `black!10`. + +- `line width` is, of course, the line width used in an object. + Typical values are `0.4pt` or `1mm`. Note that you (currently) + cannot use keys like `thin` or `thick` here, but this may change in + the future. + +- `motion` is a slightly special attribute: It allows you to specify a + path along which the object should be moved (using the `along` key). + The values given to the `entry` key for this attribute refer to a + *fraction of the distance along the path*. See the `along` key for + details. + +- `opacity` and the variants `fill opacity` and `draw opacity` animate + the opacity of an object. Allowed values range between 0 and 1. + +- `path` allows you to animate a path (it will morph). The "values" + are now paths themselves. See Section ?? for details. + +- `rotate` refers to a rotation of the object. Values for the `entry` + key are the rotation angles like `0` or `90`. + +- `scale` refers to the scaling of the object. Values are either + single scalars values (like `1` or `1.5`) or two numbers separated + by a comma (like `1,1.5` or `0.5,2`), referring to the $x$-scaling + and $y$-scaling. + +- `softpath` is a special case of the `path` attribute, see Section ?? + once more. + +- `translate` shifts the object by a certain vector. Values are points + like `\pgfpoint{1cm}{2cm}`. + +- `view` allows you to animate the view box of a view, see Section ?? + for details. + +- `visible` refers to the visibility of an object. Allowed values are + `true` and `false`. + +- `stage` is identical to `visible`, but when the object is not + animated, it will be hidden by default. + +- `xskew` and `yskew` skew the object. Attributes are angles like `0` + or `45` or even `90`. + +**The Target Object** + +As stated earlier, the ⟨options⟩ are used to specify the object whose +attribute for which an animation should be added to the picture. Indeed, +you *must* specify the object explicitly using the `whom` key and you +must do so *before* the object is created. Note that, in contrast, in +SVG you can specify an animation more or less anywhere and then use +hyper-references to link the animation to the to-be-animated object; +PGF insists that you specify the animation before the object. This is a +bit of a bother in some situations, but it is the only way to ensure +that PGF has a fighting chance to attach some additional code to the +object (which is necessary for almost all animations of the +transformation matrix). + +As explained in the introduction of this chapter, an "animation" is just +a bit of special text in the output document asking a viewer application +to animate the object at some later time. The `\pgfanimateattribute` +command inserts this special text immediately, even though it refers to +an object created only later on. Normally, this is not a problem, but +the special text should be on the same page as the to-be-animated +object. To ensure this, it suffices to call `\pgfanimateattribute` no +earlier than the beginning of the `pgfpicture` containing the object. + +**Naming the Animation** + +You can assign a name to an animation for later (or early) reference. In +particular, it is possible to begin *another* animation relative to the +beginning or end of this animation and for referencing this animation +must be assigned a name. See the `of` and `of next` keys for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfanimateattribute" + }, + pgfanimateattributecode = { + arguments = {{meta = "attribute"}, {meta = "code"}}, + details = [[ +The command works like `\pgfanimateattribute`, only instead of ⟨options⟩ +you specify some ⟨code⟩ whose job is to setup the options. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfanimateattributecode" + }, + pgfapproximatenonlineartransformation = { + details = [[ +This command will do two things: + +1. It clears the nonlinear transformations for the rest of the current + TeX scope, so only linear transformations apply. + +2. However, before removing the nonlinear transformations, the linear + transformation matrix is modified so that it mimics the effect the + nonlinear transformation had at the origin. That is, after you call + this command, drawing something near the origin will look almost the + same as if you had not called it. + + + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + \pgftransformnonlinear{\polartransformation}% see above + \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm); + + \begin{scope}[shift={(45pt,20mm)}] + % Draw something near "origin": + \draw [red] (-10pt,-10pt) -- (10pt,10pt); + \draw [red] (10pt,-10pt) -- (-10pt,10pt); + + % Now draw the same, but in the "approximate" coordinate system: + \pgfapproximatenonlineartransformation + \draw [] (-10pt,-10pt) -- (10pt,10pt); + \draw [] (10pt,-10pt) -- (-10pt,10pt); + \pgftext{foo}; + \end{scope} + \end{tikzpicture} + +This command is used by `\pgftext` and `\pgfnode` to transform text when +a nonlinear transformation is in force. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfapproximatenonlineartransformation" + }, + pgfapproximatenonlineartranslation = { + details = [[ +This command works like the normal approximation command, but it will +only approximate how the origin gets translated, it will not approximate +the rotation, skewing, or scaling that is involved. This is useful for +drawing text at the right position, but without "mutilating" the text. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + \pgftransformnonlinear{\polartransformation}% see above + \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm); + + \begin{scope}[shift={(45pt,20mm)}] + % Draw something near "origin": + \draw [red] (-10pt,-10pt) -- (10pt,10pt); + \draw [red] (10pt,-10pt) -- (-10pt,10pt); + + % Now draw the same, but in the "approximate" coordinate system: + \pgfapproximatenonlineartranslation + \draw [] (-10pt,-10pt) -- (10pt,10pt); + \draw [] (10pt,-10pt) -- (-10pt,10pt); + \pgftext{foo}; + \end{scope} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfapproximatenonlineartranslation" + }, + pgfarrowsaddtolateoptions = { + arguments = {{meta = "code"}}, + details = [[ +This command works like `\pgfarrowsaddtooptions`, only the ⟨code⟩ will +be executed "later" than the code added by the normal version of the +command. This is useful for keys that depend on the length of an arrow: +Keys like `width’` want to define the arrow width as a multiple of the +arrow length, but when the `width’` key is given, the length may not yet +have been specified. By making the computation of the width a "late" +option, we ensure that `\pgfarrowlength` will have been setup correctly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsaddtolateoptions" + }, + pgfarrowsaddtolengthscalelist = { + arguments = {{meta = "dimension register"}}, + details = [[ +Each time an arrow tip is used, the given ⟨dimension register⟩ will be +multiplied by the `scale length` factor prior to the actual drawing. You +call this command only once in the preamble somewhere. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsaddtolengthscalelist" + }, + pgfarrowsaddtooptions = { + arguments = {{meta = "code"}}, + details = [[ +This command should be called by keys with the prefix `/pgf/arrow keys` +to add code to the arrow option cache. For our `depth` key example, we +could use this key as follows: + + \pgfkeys{/pgf/arrow keys/depth/.code= + \pgfarrowsaddtooptions{\pgfmathsetlength{\pgfarrowdepth}{#1}} + +Actually, this is still not optimal since the expensive +`\pgfmathsetlength` command is now called each time an arrow tip is used +with the `depth` option set. The trick is to do the expensive operation +only once and then store only very quick code in the arrow option cache: + + \pgfkeys{/pgf/arrow keys/depth/.code= + \pgfmathsetlength{\somedimen}{#1} + \pgfarrowsaddtooptions{\pgfarrowdepth=\somedimen} % buggy + +The above code will not (yet) work since `\somedimen` will surely have a +different value when the cache is executed. The trick is to use some +`\expandafter`s: + + \pgfkeys{/pgf/arrow keys/depth/.code= + \pgfmathsetlength{\somedimen}{#1} + \expandafter\pgfarrowsaddtooptions\expandafter{\expandafter\pgfarrowdepth\expandafter=\the\somedimen} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsaddtooptions" + }, + pgfarrowsaddtowidthscalelist = { + arguments = {{meta = "dimension register"}}, + details = [[ +Works like `\pgfarrowsaddtolengthscalelist`, only for width parameters. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsaddtowidthscalelist" + }, + pgfarrowshullpoint = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ +Adds a point to the convex hull of the arrow tip. As for the previous +commands, no math parsing is done; instead PGF says `\pgf@x=`⟨x +dimension⟩ and then `\pgf@y=`⟨y dimension⟩. Thus, both "dimensions" can +contain code for advancing and thus modifying `\pgf@x` and `\pgf@y`. + +In our example we would write + + \pgfarrowshullpoint{1cm}{0pt} + \pgfarrowshullpoint{-3cm}{2cm} + \pgfarrowshullpoint{-3cm}{-2cm} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowshullpoint" + }, + pgfarrowslengthdependent = { + arguments = {{meta = "dimension"}, {meta = "length factor"}, {meta = "dummy"}}, + details = [[ +This command takes three parameters, of which the last one is ignored, +and does the "length dependent computation" described for the `width’` +and `inset’` keys. The result is returned in `\pgf@x`. + +You can setup length dependent keys using code like the following: + + \pgfkeys{/pgf/arrow keys/depth'/.code={% + \pgfarrowsthreeparameters{#1}% + \expandafter\pgfarrowsaddtolateoptions\expandafter{% + \expandafter\pgfarrowslengthdependent\pgfarrowstheparameters% compute... + \pgfarrowdepth\pgf@x% ... and store. + }% + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowslengthdependent" + }, + pgfarrowslinewidthdependent = { + arguments = { + {meta = "dimension"}, + {meta = "line width factor"}, + {meta = "outer factor"} + }, + details = [[ +This command takes three parameters and does the "line width dependent +computation" described on page ?? for the `length` key. The result is +returned in `\pgf@x`. + +The idea is that you can setup line-width dependent keys like `length` +or `width` using code like the following: + + \pgfkeys{/pgf/arrow keys/depth/.code={% + \pgfarrowsthreeparameters{#1}% + \expandafter\pgfarrowsaddtolateoptions\expandafter{% + \expandafter\pgfarrowslinewidthdependent\pgfarrowstheparameters% compute... + \pgfarrowdepth\pgf@x% ... and store. + }% + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowslinewidthdependent" + }, + pgfarrowssave = { + arguments = {{meta = "macro"}}, + details = [[ +As explained earlier, the setup code needs to "communicate" with the +drawing code via "saved values". This command get the name of a macro +and will store the value this macro had internally. Then, each time +drawing code is executed, the value of this macro will be restored. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssave" + }, + pgfarrowssavethe = { + arguments = {{meta = "register"}}, + details = [[ +Works like `\pgfarrowssave`, only the parameter must be a register and +`\the`⟨register⟩ will be saved. Typically, you will write something like + + \pgfarrowssavethe{\pgfarrowlength} + \pgfarrowssavethe{\pgfarrowwidth} + +To ensure that inside the drawing code the the dimension registers +`\pgfarrowlength` and `\pgfarrowwidth` are setup with the values they +had during the setup. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssavethe" + }, + pgfarrowssetbackend = { + arguments = {{meta = "dimension"}}, + details = [[ +Works like the command for the tip end, only it sets the back end. In +our example we would call + + \pgfarrowssettipend{-3cm} + +Defaults to `0pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssetbackend" + }, + pgfarrowssetlineend = { + arguments = {{meta = "dimension"}}, + details = [[ +Sets the line end, so in the example we have +`\pgfarrowssettipend{-1cm}`. Default to `0pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssetlineend" + }, + pgfarrowssettipend = { + arguments = {{meta = "dimension"}}, + details = [[ +When this command is called inside the setup code of an arrow tip, it +specifies that the tip of the drawn arrow will end exactly at +⟨dimension⟩. For example, for our earlier example of the large arrow +tip, where the tip end was at 1cm, we would call + + \pgfarrowssettipend{1cm} + +Note that for efficiency reasons, the ⟨dimension⟩ is not passed through +`\pgfmathsetlength`; rather what happens is that `\pgf@x=`⟨dimension⟩ +gets executed. In particular, you can pack further computations into the +⟨dimension⟩ by simply starting it with a number and then appending some +code that modifies `\pgf@x`. Here is an example where instead of 1cm we +use $1\mathrm{cm} - \frac12\mathrm{linewidth}$ as the tip end: + + \pgfarrowssettipend{1cm\advance\pgf@x by-.5\pgflinewidth} + +If the command is not called at all inside the setup code, the tip end +is set to `0pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssettipend" + }, + pgfarrowssetvisualbackend = { + arguments = {{meta = "dimension"}}, + details = [[ +Sets the visual back end, `\pgfarrowssetvisualbackend{-2cm}` in our +example. Default to the value of the normal back end. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssetvisualbackend" + }, + pgfarrowssetvisualtipend = { + arguments = {{meta = "dimension"}}, + details = [[ +Sets the visual tip end. Default to the value of the normal tip end and, +thus, we need not set it in our example. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssetvisualtipend" + }, + pgfarrowsthreeparameters = { + arguments = {{meta = "line-width dependent size specification"}}, + details = [[ +This command is useful for parsing the values given to keys like +`length` or `width` the expect a dimension followed optionally for some +numbers. This command converts the ⟨line-width dependent size +specification⟩, which may consist of one, two, or three numbers, into a +triple of three numbers in curly braces, which gets stored in the macro +`\pgfarrowstheparameters`. Here is an example, where `\showvalueofmacro` +is used in this example to show the value stored in a macro: + + \makeatletter + \def\showvalueofmacro#1{% + \texttt{\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\pgfutil@gobble\expandafter\expandafter\expandafter\string\expandafter\csname#1\endcsname} + }% + + \pgfarrowsthreeparameters{2pt 1} + \showvalueofmacro\pgfarrowstheparameters +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsthreeparameters" + }, + pgfarrowsupperhullpoint = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ +This command works like the previous command, only it normally adds +*two* points to the convex hull: First, the point +$(⟨x dimension⟩,⟨y dimension⟩)$ and, secondly, the point +$(⟨x dimension⟩,-⟨y dimension⟩)$. However, the second point is only +added if the arrow is not a harpoon. + +Thus, in our example we could simplify the convex hull to + + \pgfarrowshullpoint{1cm}{0pt} + \pgfarrowsupperhullpoint{-3cm}{2cm} + +If the ⟨y dimension⟩ is zero or less, only one point, namely +$(⟨x dimension⟩,⟨y dimension⟩)$, is added to the hull. Thus, we could +also have used the upper convex hull command in the first of the two of +the above commands. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsupperhullpoint" + }, + pgfcalendar = { + arguments = { + {meta = "prefix"}, + {meta = "start date"}, + {meta = "end date"}, + {meta = "rendering code"} + }, + details = [[ +This command can be used to typeset a calendar. It is a very general +command, the actual work has to be done by giving clever implementations +of ⟨rendering code⟩. Note that this macro need *not* be called inside a +`{pgfpicture}` environment (even though it typically will be) and you +can use it to typeset calendars in normal TeX or using packages other +than PGF. + +**Basic typesetting process.** A calendar is typeset as follows: The +⟨start date⟩ and ⟨end date⟩ specify a range of dates. For each date in +this range the ⟨rendering code⟩ is executed with certain macros setup to +yield information about the *current date* (the current date in the +enumeration of dates of the range). Typically, the ⟨rendering code⟩ +places nodes inside a picture, but it can do other things as well. Note +that it is also the job of the ⟨rendering code⟩ to position the calendar +correctly. + +The different calls of the ⟨rending code⟩ are not surrounded by +TeX groups (though you can do so yourself, of course). This means that +settings can accumulate between different calls, which is often +desirable and useful. + +**Information about the current date.** Inside the ⟨rendering code⟩, +different macros can be access: + +- `\pgfcalendarprefix` The ⟨prefix⟩ parameter. This prefix is + recommended for nodes inside the calendar, but you have to use it + yourself explicitly. + +- `\pgfcalendarbeginiso` The ⟨start date⟩ of range being typeset in + ISO format (like 2006-01-10). + +- `\pgfcalendarbeginjulian` Julian day number of ⟨start date⟩. + +- `\pgfcalendarendiso` The ⟨end date⟩ of range being typeset in ISO + format. + +- `\pgfcalendarendjulian` Julian day number of ⟨end date⟩. + +- `\pgfcalendarcurrentjulian` This TeX count holds the Julian day + number of the day currently being rendered. + +- `\pgfcalendarcurrentweekday` The weekday (a number with zero + representing Monday) of the current date. + +- `\pgfcalendarcurrentyear` The year of the current date. + +- `\pgfcalendarcurrentmonth` The month of the current date (always two + digits with a leading zero, if necessary). + +- `\pgfcalendarcurrentday` The day of month of the current date + (always two digits). + +**The `\ifdate` command.** Inside the `\pgfcalendar` the macro `\ifdate` +is available locally: + +**Examples.** In a first example, let us create a very simple calendar: +It just lists the dates in a certain range. + + \pgfcalendar{cal}{2007-01-20}{2007-02-10}{\pgfcalendarcurrentday\ } + +Let us now make this a little more interesting: Let us add a line break +after each Sunday. + + \pgfcalendar{cal}{2007-01-20}{2007-02-10} + { + \pgfcalendarcurrentday\ + \ifdate{Sunday}{\par}{} + } + +We now want to have all Mondays to be aligned on a column. For this, +different approaches work. Here is one based positioning each day +horizontally using a skip. + + \pgfcalendar{cal}{2007-01-20}{2007-02-10} + {% + \leavevmode% + \hbox to0pt{\hskip\pgfcalendarcurrentweekday cm\pgfcalendarcurrentday\hss}% + \ifdate{Sunday}{\par}{}% + } + +Let us now typeset two complete months. + + \pgfcalendar{cal}{2007-01-01}{2007-02-28}{% + \ifdate{day of month=1}{ + \par\bigskip\hbox to7.5cm{\itshape\hss\pgfcalendarshorthand mt\hss}\par + }{}% + \leavevmode% + {% + \ifdate{weekend}{\color{black!50}}{\color{black}}% + \hbox to0pt{% + \hskip\pgfcalendarcurrentweekday cm% + \hbox to1cm{\hss\pgfcalendarshorthand d-}\hss% + }% + }% + \ifdate{Sunday}{\par}{}% + } + +For our final example, we use a `{tikzpicture}`. + + \begin{tikzpicture} + \pgfcalendar{cal}{2007-01-20}{2007-02-10}{% + \ifdate{workday} + {\tikzset{filling/.style={fill=blue!20}}} + {\tikzset{filling/.style={fill=red!20}}} + \node (\pgfcalendarsuggestedname) at (\pgfcalendarcurrentweekday,0) + [anchor=base,circle,filling] {\pgfcalendarcurrentday}; + \ifdate{Sunday}{\pgftransformyshift{-3em}}{}% + } + \draw (cal-2007-01-21) -- (cal-2007-02-03); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendar" + }, + pgfcalendardatetojulian = { + arguments = {{meta = "date"}, {meta = "counter"}}, + details = [[ +This macro converts a date in a format to be described in a moment to +the Julian day number in the Gregorian calendar. The ⟨date⟩ should +expand to a string of the following form: + +1. It should start with a number representing the year. Use `\year` for + the current year, that is, the year the file is being typeset. + +2. The year must be followed by a hyphen. + +3. Next should come a number representing the month. Use `\month` for + the current month. You can, but need not, use leading zeros. For + example, `02` represents February, just like `2`. + +4. The month must also be followed by a hyphen. + +5. Next you must either provide a day of month (again, a number and, + again, `\day` yields the current day of month) or the keyword + `last`. This keyword refers to the last day of the month, which is + automatically computed (and which is a bit tricky to compute, + especially for February). + +6. Optionally, you can next provide a plus sign followed by positive or + negative number. This number of days will be added to the computed + date. + +Here are some examples: + +- `2006-01-01` refers to the first day of 2006. + +- `2006-02-last` refers to February 28, 2006. + +- `\year-\month-\day` refers to today. + +- `2006-01-01+2` refers to January 3, 2006. + +- `\year-\month-\day+1` refers to tomorrow. + +- `\year-\month-\day+-1` refers to yesterday. + +The conversion method is taken from the English Wikipedia entry on +Julian days. + +`\pgfcalendardatetojulian{2007-01-14}{\mycount}` sets `\mycount` to . +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendardatetojulian" + }, + pgfcalendareastersunday = { + arguments = {{meta = "year"}, {meta = "counter"}}, + details = [[ +This command computes the date of Easter Sunday as a Julian date and +stores it in ⟨counter⟩. + +`\pgfcalendareastersunday{2019}{\mycount}` sets `\mycount` to , which +corresponds to ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendareastersunday" + }, + pgfcalendarifdate = { + arguments = { + {meta = "date"}, + {meta = "tests"}, + {meta = "code"}, + {meta = "else code"} + }, + details = [[ +\[pgfcalendarifdate\] This command is used to execute code based on +properties of ⟨date⟩. The ⟨date⟩ must be a date in ISO-format. For this +date, the ⟨tests⟩ are checked (to be detailed later) and if one of the +tests succeeds, the ⟨code⟩ is executed. If none of the tests succeeds, +the ⟨else code⟩ is executed. + +`\pgfcalendarifdate{2007-02-07}{Wednesday}{Is a Wednesday}{Is not a Wednesday}` +yields ``. + +The ⟨tests⟩ is a comma-separated list of key--value pairs. The following +are defined by default: + +This test is passed by all dates. This test is passed by all dates that +are Mondays. as above. as above. as above. as above. as above. as above. +Passed by Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays. Passed +by Saturdays and Sundays. `=`⟨reference⟩ The ⟨reference⟩ can be in one +of two forms: Either, it is a full ISO format date like `2007-01-01` or +the year may be missing as in `12-31`. In the first case, the test is +passed if ⟨date⟩ is the same as ⟨reference⟩. In the second case, the +test is passed if the month and day part of ⟨date⟩ is the same as +⟨reference⟩. + +For example, the test `equals=2007-01-10` will only be passed by this +particular date. The test `equals=05-01` will be passed by every first +of May on any year. `=`⟨reference⟩ This test works similarly to the +`equals` test, only it is checked whether ⟨date⟩ is equal to ⟨reference⟩ +or to any later date. Again, the ⟨reference⟩ can be a full date like +`2007-01-01` or a short version like `07-01`. For example, +`at least=07-01` is true for every day in the second half of any year. +`=`⟨reference⟩ as above. `=`⟨start reference⟩` and `⟨end reference⟩ This +test checks whether the current date lies between the two given +reference dates. Both full and short version may be given. + +For example `between=2007-01-01 and 2007-02-28` is true for the days in +January and February of 2007. + +For another example, `between=05-01 and 05-07` is true for the days of +the first week of May of any year. `=`⟨number⟩ Passed by the day of +month of the ⟨date⟩ that is ⟨number⟩. For example, the test +`day of month=1` is passed by every first of every month. `=`⟨number⟩ +Passed by the day of month of the ⟨date⟩ that is ⟨number⟩ from the end +of the month. For example, the test `end of month=1` is passed by the +last day of every month, the test `end of month=2` is passed by the +second last day of every month. If ⟨number⟩ is omitted, it is assumed to +be `1`. `=`⟨number⟩ This test checks whether the given date is Easter +Sunday. The optional number can be used for offsets from Easter Sunday, +e.g. `Easter=-3` for Maundy Thursday, `Easter=-2` for Good Friday, +`Easter=1` for Easter Monday. Since the dates of other Christian +holidays are determined by the date of Easter, these can be accessed as +well, e.g. `Easter=39` for Feast of the Ascension, `Easter=49` for +Pentecost, and `Easter=50` for Whit Monday. + +In addition to the above checks, you can also define new checks. To do +so, you must add a new key to the path `/pgf/calendar/` using the +`\pgfkeys` command. The job of the code of this new key is to possibly +set the TeX-if `\ifpgfcalendarmatches` to true (if it is already true, +no action should be taken) to indicate that the ⟨date⟩ passes the test +setup by this new key. + +In order to perform the test, the key code needs to know the date that +should be checked. The date is available through a macro, but a whole +bunch of additional information about this date is also available +through the following macros: + +- `\pgfcalendarifdatejulian` is the Julian day number of the ⟨date⟩ to + be checked. + +- `\pgfcalendarifdateweekday` is the weekday of the ⟨date⟩ to be + checked. + +- `\pgfcalendarifdateyear` is the year of the ⟨date⟩ to be checked. + +- `\pgfcalendarifdatemonth` is the month of the ⟨date⟩ to be checked. + +- `\pgfcalendarifdateday` is the day of month of the ⟨date⟩ to be + checked. + +For example, let us define a new key that checks whether the ⟨date⟩ is a +Workers day (May 1st). This can be done as follows: + + \pgfkeys{/pgf/calendar/workers day/.code=% + { + \ifnum\pgfcalendarifdatemonth=5\relax + \ifnum\pgfcalendarifdateday=1\relax + \pgfcalendarmatchestrue + \fi + \fi + }} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarifdate" + }, + pgfcalendarjuliantodate = { + arguments = { + {meta = "Julian day"}, + {meta = "year macro"}, + {meta = "month macro"}, + {meta = "day macro"} + }, + details = [[ +This command converts a Julian day number to an ISO-date. The ⟨Julian +day⟩ must be a number or TeX counter, the ⟨year macro⟩, ⟨month macro⟩ +and ⟨day macro⟩ must be TeX macro names. They will be set to numbers +representing the year, month, and day of the given Julian day in the +Gregorian calendar. + +The ⟨year macro⟩ will be assigned the year without leading zeros. Note +that this macro will produce year 0 (as opposed to other calendars, +where year 0 does not exist). However, if you really need calendars for +before the year 1, it is expected that you know what you are doing +anyway. + +The ⟨month macro⟩ gets assigned a two-digit number representing the +month (with a leading zero, if necessary). Thus, the macro is set to +`01` for January. + +The ⟨day macro⟩ gets assigned a two-digit number representing the day of +the month (again, possibly with a leading zero). + +To convert a Julian day number to an ISO-date you use code like the +following: + + \pgfcalendarjuliantodate{2454115}{\myyear}{\mymonth}{\myday} + \edef\isodate{\myyear-\mymonth-\myday} + +The above code sets `\isodate` to ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarjuliantodate" + }, + pgfcalendarjuliantoweekday = { + arguments = {{meta = "Julian day"}, {meta = "week day counter"}}, + details = [[ +This command converts a Julian day to a week day by computing the day +modulo 7. The ⟨week day counter⟩ must be a TeX counter. It will be set +to 0 for a Monday, to 1 for a Tuesday, and so on. + +`\pgfcalendarjuliantoweekday{2454115}{\mycount}` sets `\mycount` to (it +was a Sunday). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarjuliantoweekday" + }, + pgfcalendarmonthname = { + arguments = {{meta = "month number"}}, + details = [[ +This command expands to a textual representation of the month, which is +given by the ⟨month number⟩. + +`\pgfcalendarmonthname{12}` yields ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarmonthname" + }, + pgfcalendarmonthshortname = { + arguments = {{meta = "month number"}}, + details = [[ +As above, only an abbreviated version is produced. + +`\pgfcalendarmonthshortname{12}` yields ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarmonthshortname" + }, + pgfcalendarshorthand = { + arguments = {{meta = "kind"}, {meta = "representation"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarshorthand" + }, + pgfcalendarsuggestedname = { + details = [[ +This macro expands to a suggested name for nodes representing days in a +calendar. If the ⟨prefix⟩ is empty, it expands to the empty string, +otherwise it expands to the ⟨prefix⟩ of the calendar, followed by a +hyphen, followed by the ISO format version of the date. Thus, when the +date `2007-01-01` is typeset in a calendar for the prefix `mycal`, the +macro expands to `mycal-2007-01-01`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarsuggestedname" + }, + pgfcalendarweekdayname = { + arguments = {{meta = "week day number"}}, + details = [[ +This command expands to a textual representation of the day of week, +given by the ⟨week day number⟩. Thus, `\pgfcalendarweekdayname{0}` +expands to `Monday` if the current language is English and to `Montag` +if the current language is German, and so on. See Section ?? for more +details on translations. + +`\pgfcalendarweekdayname{2}` yields ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarweekdayname" + }, + pgfcalendarweekdayshortname = { + arguments = {{meta = "week day number"}}, + details = [[ +This command works similarly to the previous command, only an +abbreviated version of the week day is produced. + +`\pgfcalendarweekdayshortname{2}` yields ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarweekdayshortname" + }, + pgfclearid = { + details = [[ +Clears the current id (and type) for the local scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfclearid" + }, + pgfcoordinate = { + arguments = {{meta = "name"}, {meta = "coordinate"}}, + details = [[ +This command creates a node of shape `coordinate` at the given +⟨coordinate⟩. Exactly the same effect can be achieved using first a +shift of the coordinate system to ⟨coordinate⟩, followed by creating a +node of shape `coordinate` named ⟨name⟩. However, this command is easier +and more natural to use and, more importantly, it is much faster. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcoordinate" + }, + pgfcurvilineardistancetotime = { + arguments = {{meta = "distance"}}, + details = [[ +This command does a "distance-to-time-conversion": It tries to compute a +time $t$, returned in `\pgf@x`, that corresponds to travelling +⟨distance⟩ along the curve that has last been installed using the +command `\pgfsetcurvilinearbeziercurve`. The distance-to-time-conversion +uses the precomputations done by that command. Note that several +compromises had to be made between speed and accuracy: + +- The conversion will be best near the start of the curve. + +- The more "degenerate" the curve, the worse the results. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcurvilineardistancetotime" + }, + pgfdata = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "inline data"} + }, + details = [[ +This command is used to feed data to the visualization pipeline. This +command can only be used when a data visualization object has been +properly setup, see Section ??. + +**Basic options.** The `\pgfdata` command may be followed by ⟨options⟩, +which are executed with the path `/pgf/data/`. Depending on these +options, the ⟨options⟩ may either be followed by ⟨inline data⟩ or, +alternatively, no ⟨inline data⟩ is present and the data is read from an +external source. + +The first important option is ⟨source⟩, which governs which of these two +alternatives applies: + +The second important key is `format`, which is used to specify the data +format: + +In case all your data is in a certain format, you may wish to generally +set the above key somewhere at the beginning of your file. +Alternatively, you can use the following style to setup the `format` key +and possibly further keys concerning the data format: + +**Gathering of the data.** Once the data format and the source have been +decided upon, the data is "gathered". During this phase the data is not +actually parsed in detail, but just gathered so that it can later be +parsed during the visualization. There are two different ways in which +the data is gathered: + +- In case you have specified an external source, the data + visualization object is told (by means of invoking the `add data` + method) that it should (later) read data from the file specified by + the `source` key using the format specified by the `format` key. The + file is not read at this point, but only later during the actual + visualization. + +- Otherwise, namely when data is given inline, depending on which + format is used, some catcodes get changed. This is necessary since + TeX's special characters are often not-so-special in a certain + format. + + Independently of the format, the end-of-line character (carriage + return) is made an active character. + + Finally, the ⟨inline data⟩ is then read as a normal argument and the + data visualization object is told that later on it should parse this + data using the given format parser. Note that in this case the data + visualization object must store the whole data internally. + +In both cases the "data visualization object" is the object stored in +the `/pgf/data visualization/obj` key. + +**Parsing of the data.** During the actual data visualization, all code +that has been added to the data visualization object by means of the +`add data` method is executed several times. It is the job of this code +to call the `\pgfdatapoint` method for all data points present in the +data. + +When the `\pgfdata` method calls `add data`, the code that is passed to +the data visualization object is just a call to internal macros of +`\pgfdata`, which are able to parse the data stored in an external file +or in the inlined data. Independently of where the data is stored, these +macros always do the following: + +1. The catcodes are setup according to what the data format requires. + +2. Format-specific startup code gets called, which can initialize + internal variables of the parsing process. (The catcode changes are + not part of the startup code since in order to read inline data + `\pgfdata` must be able to setup to temporarily setup the catcodes + needed later on by the parsers, but since no reading is to be done, + no startup code should be called at this point.) + +3. For each line of the data a format-specific code handler, which + depends on the data format, is called. This handler gets the current + line as input and should call `\pgfdatapoint` once for each data + point that is encoded by this line (a line might define multiple + data points or none at all). Empty lines are handled by special + format-specific code. + +4. At the end, format-specific end code is executed. + +For an example of how this works, see the description of the +`\pgfdeclaredataformat` command. + +**Data sets.** There are three options that allow you to create *data +sets*. Such a data set is essentially a macro that stores a pre-parsed +set of data that can be used multiple times in subsequent visualizations +(or even in the same visualization). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdata" + }, + pgfdeclarearrow = { + arguments = {{meta = "config"}}, + details = [[ +This command is both used to define a new arrow tip kind and to to +declare a so-called shorthand. We have a look at the case that a +complete new arrow tip kind is created and then have a look how the +command can be used to create shorthands. + +**Defining a Complete New Arrow Tip Kind.** The ⟨config⟩ is a key--value +list in which different keys are used to setup the to-be defined arrow. +The following keys can be given: + +- `name``=`⟨name⟩ or `name=`⟨start name⟩`-`⟨end name⟩ + + This defines the name of the arrow tip. It is legal to define an + arrow tip a second time, in this case the previous definition will + be overwritten in the current TeX scope. It is customary to use a + name with an uppercase first letter for a "complete" arrow tip kind. + Short names and lower case names should be used for shorthands that + change their meaning inside a document, while arrow tips with + uppercase first letters should not be redefined. + + If the name contains a hyphen, the second syntax is assumed and + everything before the hyphen will be the name used in start arrow + specifications, while the text after the hyphen is the name used in + end specifications. + +- `parameters``=``{list of macros}` + + As explained earlier, an arrow tip typically needs to be redrawn + each time an option like `length` or `inset` is changed. However, + for some arrow tips, the `inset` has no influence, while for other + it is important whether the arrow is reversed or not. (How keys like + `length` actually set TeX dimensions like `\pgfarrowlength` is + explained in Section ??.) + + The job of the `parameters` key is to specify which dependencies the + arrow tip has. Everything that will influence any of the parameters + computed in the setup code or used in the drawing code should be + listed here. + + The ⟨list of macros⟩ will be used inside a `\csname`-`\endcsname` + pair and should expand to the current values of the relevant + parameters have. For example, if the arrow tip depends on the + current value of `\pgfarrowlength` and `\pgfarrowwidth` only, then + ⟨list of macros⟩ should be set to + `\the\pgfarrowlength,\the\pgfarrowwidth`. (Actually, the comma is + optional, the ⟨list of macros⟩ does not really have to be a list, + just something that can be expanded unambiguously.) + + Note that the line width (`\pgflinewidth`) and the inner line width + (`\pgfinnerlinewidth`) are always parameters and need not be + specified in the `parameters`. + + It is important to get this parameter right. Otherwise, arrow tips + may look wrong because PGF thinks that it can reuse some code when, + in reality, this code actually depends on a parameter not listed + here. + +- `setup code``=``{code}` + + When an arrow tip is used, the value stored in `parameters` is + expanded and it is tested whether the result was encountered before. + If not, the ⟨code⟩ gets executed (only this once). The code can now + do arbitrarily complicated computations the prepare the later + drawing of the arrow tip. Also the ⟨code⟩ must specify the different + tip and back ends and the convex hull points. This is done by + calling the following macros inside the ⟨code⟩: + +- `drawing code``=``{code}` + + This code will be executed at least once for each setting of the + parameters when the time arrow tip is actually drawn. Usually, this + one execution will be all and the low-level commands generated + inside the ⟨code⟩ will we stored in a special cache; but in some + cases the ⟨code⟩ gets executed each time the arrow tip is used, so + do not assume anything about it. Inside the ⟨code⟩, you have access + to all values that were saved in the setup code as well as to the + line width. + + The ⟨code⟩ should draw the arrow tip "going right along the + $x$-axis". PGF will take care of setting up a canvas transformation + beforehand to a rotation such that when the drawing is rendered, the + arrow tip that is actually drawn points in the direction of the + line. Alternatively, when bending is switched on, even more + complicated low-level transformations will be done automatically. + + The are some special considerations concerning the ⟨code⟩: + + - In the ⟨code⟩ you may *not* use `\pgfusepath` since this would + try to add arrow tips to the arrow tip and lead to a recursion. + Use the "quick" versions `\pgfusepathqstroke` and so on instead, + which never try to add arrow tips. + + - If you stroke the path that you construct, you should first set + the dashing to solid and set up fixed joins and caps, as needed. + This will ensure that the arrow tip will always look the same. + + - When the arrow tip code is executed, it is automatically put + inside a low-level scope, so nothing will "leak out" from the + scope. + + - The high-level coordinate transformation matrix will be set to + the identity matrix when the code is executed for the first + time. + +- `cache``=`⟨true or false⟩ + + When set to `true`, which is the default, the ⟨code⟩ will be + executed only once for a particular value of parameters and the + low-level commands created by the drawing code (using the system + layer protocol subsystem, see Section ??) will be cached and reused + later on. However, when the drawing code contains "uncachable" code + like a call to `\pgftext`, caching must be switched off by saying + `cache=false`. + +- `bending mode``=`⟨mode⟩ + + This key is important only when the `bend` option is used with an + arrow, see Section ?? for an introduction to this option. The `bend` + option asks us to, well, bend the arrow head. For some arrow head + this is not possible or leads to very strange drawings (for + instance, when the `\pgftext` command is used) and then it is better + to switch bending off for the arrow head (`flex` will then be used + instead). To achieve this, set ⟨mode⟩ to `none`. + + For most arrow tips it does, however, make sense to bend them. There + are (at least) two different mathematical ways of doing so, see + Section ?? for details. Which of these ways is use can be configured + by setting ⟨mode⟩ to either `orthogonal` or to `polar`. It is best + to try simply try out both when designing an arrow tip to see which + works better. Since `orthogonal` is quicker and often gives good + oder even better results, it is the default. Some arrow tips, + however, profit from saying `bending mode=polar`. + +- `defaults``=`⟨arrow keys⟩ + + The ⟨arrow keys⟩ allow you to configure the default values for the + parameters on which an arrow tip depends. The ⟨arrow keys⟩ will be + executed first before any other arrow tip options are executed, see + Section ?? for the exact sequence. Also see Section ?? below for + more details on arrow options. + +This concludes the description of the keys you provide for the +declaration of an arrow. Let us now have a look at a simple example that +uses these features: We want to define an arrow tip kind `foo` that +produces the arrow tip we used as our running example. However, to make +things a bit more interesting, let us make it "configurable" insofar as +the length of the arrow tip can be configured using the `length` option, +which sets the `\pgfarrowlength`. By default, this length should be the +gigantic 4cm we say in the example, but uses should be able to set it to +anything they like. We will not worry about the arrow width or insets, +of arrow line width, or harpoons, or anything else in this example to +keep it simple. + +Here is the code: + + \pgfdeclarearrow{ + name = foo, + parameters = { \the\pgfarrowlength }, + setup code = { + % The different end values: + \pgfarrowssettipend{.25\pgfarrowlength} + \pgfarrowssetlineend{-.25\pgfarrowlength} + \pgfarrowssetvisualbackend{-.5\pgfarrowlength} + \pgfarrowssetbackend{-.75\pgfarrowlength} + % The hull + \pgfarrowshullpoint{.25\pgfarrowlength}{0pt} + \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength} + \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength} + % Saves: Only the length: + \pgfarrowssavethe\pgfarrowlength + }, + drawing code = { + \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}} + \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}} + \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}} + \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}} + \pgfpathclose + \pgfusepathqfill + }, + defaults = { length = 4cm } + } + +We can now use it: + + \tikz \draw [-foo] (0,0) -- (8,0); + + \tikz \draw [-{foo[length=2cm,bend]}] (0,0) to [bend left] (3,0); + +**Defining a Shorthand.** The `\pgfdeclarearrow` command can also used +to define *shorthands*. This works as follows: + +- First, you must provide a `name` just in the same way as when you + define a full-flung new arrow tip kind. + +- Second, instead of all of the other options listed above, you just + use one more option: + + `means``=`⟨end arrow specification⟩ + + This sets up things so that whenever ⟨name⟩ is now used in an arrow + specification, it will be replaced by the ⟨end arrow specification⟩ + (the problems resulting form the ⟨name⟩ begin used in a start arrow + specification are taken care of automatically). See also Section ?? + for details on the order in which options get executed in such + cases. + + Note that the ⟨end arrow specification⟩ will be executed immediately + to build the so-called arrow option caches, a concept explored in + more detail in Section ??. In practice, this has mainly two effects: + First, all arrow tips referred to in the specification must already + exist (at least as "dummy" versions). Second, all dimensions + mentioned in options of the ⟨end arrow specification⟩ will be + evaluated immediately. For instance, when you write + + \pgfdeclarearrow{ name=foo, means = bar[length=2cm+\mydimen] } + + The value `2cm+\mydimen` is evaluated immediately. When `foo` is + used later on and `\mydimen` has changed, this has no effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarearrow" + }, + pgfdeclaredataformat = { + arguments = { + {meta = "format name"}, + {meta = "catcode code"}, + {meta = "startup code"}, + {meta = "line arguments"}, + {meta = "line code"}, + {meta = "empty line code"}, + {meta = "end code"} + }, + details = [[ +This command defines a new data format called ⟨format name⟩, which can +subsequently be used in the `\pgfdata` command. (The TikZ's `data` maps +directly to `\pgfdata`, so the following applies to TikZ as well.) + +As explained in the description of the `\pgfdata` command, when data is +being parsed that is formatted according to ⟨format name⟩, the following +happens: + +1. The ⟨catcode code⟩ is executed. This code should just contain + catcode changes. The ⟨catcode code⟩ will also be executed when + inline data is read. + +2. Next, the ⟨startup code⟩ is executed. + +3. Next, for each non-empty line of the data, the line is passed to a + macro whose argument list is given by ⟨line arguments⟩ and whose + body is given by ⟨line code⟩. The idea is that you can use TeX's + powerful pattern matching capabilities to parse the non-empty lines. + See also the below example. + +4. Empty lines are not processed by the ⟨line code⟩, but rather by the + ⟨empty line code⟩. Typically, empty lines can simply be ignored and + in this case you can let this parameter be empty. + +5. At the end of the data, the ⟨end code⟩ is executed. + +As an example, let us now define a simple data format for reading files +formatted in the following manner: Each line should contain a coordinate +pair as in `(1.2,3.2)`, so two numbers separated by a comma and +surrounded by parentheses. To make things more interesting, suppose that +the hash mark symbol can be used to indicate comments. Here is an +example of some data given in this format: + + # This is some data formatted according to the "coordinates" format + (0,0) + (0.5,0.25) + (1,1) + (1.5,2.25) + (2,4) + +A format parser for this format could be defined as follows: + + \pgfdeclaredataformat{coordinates} + % First comes the catcode argument. We turn the hash mark into a comment character. + {\catcode`\#=14\relax} + % Second comes the startup code. Since we do not need to setup things, we can leave + % it empty. Note that we could also set it to something like \begingroup, provided we + % put an \endgroup in the end code + {} + % Now comes the arguments for non-empty lines. Well, these should be of the form + % (#1,#2), so we specify that: + {(#1,#2)} + % Now we must do something with a line of this form. We store the #1 argument in + % /data point/x and #2 in /data point/y. Then we call \pgfdatapoint to create a data point. + { + \pgfkeyssetvalue{/data point/x}{#1} + \pgfkeyssetvalue{/data point/y}{#2} + \pgfdatapoint + } + % We ignore empty lines: + {} + % And we also have no end-of-line code. + {} + +This format could now be used as follows: + + \begin{tikzpicture} + \datavisualization[school book axes, visualize as smooth line] + data [format=coordinates] { + # This is some data formatted according + # to the "coordinates" format + (0,0) + (0.5,0.25) + (1,1) + (1.5,2.25) + (2,4) + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclaredataformat" + }, + pgfdeclaredecoration = { + arguments = {{meta = "name"}, {meta = "initial state"}, {meta = "states"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclaredecoration" + }, + pgfdeclarefading = { + arguments = {{meta = "name"}, {meta = "contents"}}, + details = [[ +This command declares a fading named ⟨name⟩ for later use. The "picture" +on which the fading is based is given by the ⟨contents⟩. The ⟨contents⟩ +are normally typeset in a TeX box. The resulting box is then used as the +"picture". In particular, inside the ⟨contents⟩ you must explicitly open +a `{pgfpicture}` environment if you wish to use PGF commands. + +Let's start with an easy example. Our first fading picture is just some +text: + + \pgfdeclarefading{fading1}{\textcolor{white}{Ti\emph{k}Z}} + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + \pgfsetfading{fading1}{\pgftransformshift{\pgfpoint{1cm}{1cm}}} + \fill [red] (0,0) rectangle (2,2); + \end{tikzpicture} + +What's happening here? The "fading picture" is mostly transparent, +except for the pixels that are part of the word Ti*k*Z. Now, these +pixels are *white* and, thus, have a high luminosity. This in turn means +that these pixels of the fading will be highly opaque. For this reason, +only those pixels of the big red rectangle "shine through" that are at +the positions of these opaque pixels. + +It is somewhat counter-intuitive that the white pixels in a fading +picture are opaque in a fading. For this reason, the color +`pgftransparent` is defined to be the same as `black`. This allows one +to write `pgftransparent` for completely transparent parts of a fading +picture and `pgftransparent!0` for the opaque parts and things like +`pgftransparent!20` for parts that are 20% transparent. + +Furthermore, the color `pgftransparent!0` (which is the same as white +and which corresponds to completely opaque) is installed at the +beginning of a fading picture. Thus, in the above example the +`\color{white}` was not really necessary. + +Next, let us create a fading that gets more and more transparent as we +go from left to right. For this, we put a shading inside the fading +picture that has the color `pgftransparent!0` at the left-hand side and +the color `pgftransparent!100` at the right-hand side. + + \pgfdeclarefading{fading2} + {\tikz \shade[left color=pgftransparent!0, + right color=pgftransparent!100] (0,0) rectangle (2,2);} + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}}} + \fill [red] (0,0) rectangle (2,2); + \end{tikzpicture} + +In our final example, we create a fading that is based on a radial +shading. + + \pgfdeclareradialshading{myshading}{\pgfpointorigin} + { + color(0mm)=(pgftransparent!0); + color(5mm)=(pgftransparent!0); + color(8mm)=(pgftransparent!100); + color(15mm)=(pgftransparent!100) + } + \pgfdeclarefading{fading3}{\pgfuseshading{myshading}} + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + \pgfsetfading{fading3}{\pgftransformshift{\pgfpoint{1cm}{1cm}}} + \fill [red] (0,0) rectangle (2,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarefading" + }, + pgfdeclarefunctionalshading = { + arguments = { + {delimiters = {"[", "]"}, meta = "color list", optional = true}, + {meta = "shading name"}, + {meta = "lower left corner"}, + {meta = "upper right corner"}, + {meta = "init code"}, + {meta = "type 4 function"} + }, + details = [[ +*Warning: These shadings are the least portable of all and they put the +heaviest burden of the renderer. They are slow and, possibly, will not +print correctly!* + +This command creates a *functional shading*. For such a shading, the +color of each point is calculated by calling a function that takes the +coordinates of the point as input and yields the color as an output. +Note that the function is evaluated by the *renderer*, not by PGF or +TeX or someone else at compile-time. This means that the evaluation of +this function has to be done *extremely quickly* and the function should +be *very simple*. For this reason, only a very restricted set of +operations are possible in the function and functions should be kept +small. Any errors in the function will only be noticed by the renderer. + +The syntax for specifying functions is the following: You use a +simplified form of a subset of the PostScript language. This subset will +be understood by the PDF-renderer (yes, PDF-renderers do have a basic +understanding of PostScript) and also by PostScript renders. This subset +is detailed in Section 3.9.4 of the PDF-specification (version 1.7). In +essence, the specification states that these functions may contain +"expressions involving integers, real numbers, and boolean values only. +There are no composite data structures such as strings or arrays, no +procedures, and no variables or names." The allowed operators are +(exactly) the following: `abs`, `add`, `atan`, `ceiling`, `cos`, `cvi`, +`cvr`, `div`, `exp`, `floor`, `idiv`, `ln`, `log`, `mod`, `mul`, `neg`, +`round`, `sin`, `sqrt`, `sub`, `truncate`, `and`, `bitshift`, `eq`, +`false`, `ge`, `gt`, `le`, `lt`, `ne`, `not`, `or`, `true`, `xor`, `if`, +`ifelse`, `copy`, `dup`, `exch`, `index`, `pop`. + +When the function is evaluated, the top two stack elements are the +coordinates of the point for which the color should be computed. The +coordinates are dimensionless and given in big points, so for the +coordinate $(50bp, 72.27pt)$ the top two stack elements would be `50.0` +and `72.0`. Otherwise, the (virtual) stack is empty (or should be +treated as if it were empty). The function should then replace these two +values by three values, representing the red, green, and blue color of +the point for an RGB shading, four colors, representing the cyan, +magenta, yellow, and black color of the point for a CMYK shading, or one +value representing the gray color for a grayscale shading. The numbers +should be real values, not integers since, Apple's PDF renderer is +broken in this regard (use `cvr` at the end if necessary). + +Conceptually, the function will be evaluated once for each point of the +rectangle ⟨lower left corner⟩ to ⟨upper right corner⟩, which should be a +PGF-point expression like `\pgfpoint{100bp}{100bp}`. A renderer may +choose to evaluate the function at less points, but, in principle, the +function will be evaluated for each pixel independently. + +Because of the rather difficult PostScript syntax, use this macro only +*if you know what you are doing* (or if you are adventurous, of course). + +As for other shadings, the optional ⟨color list⟩ is used to determine +whether a shading needs to be recalculated when a color has changed. + +The ⟨init code⟩ is executed each time a shading is (re)calculated. +Typically, it will contain code to extract coordinates from colors. + + \pgfdeclarefunctionalshading{twospots} + {\pgfpointorigin}{\pgfpoint{4cm}{4cm}}{}{ + % Save coordinates for later + 2 copy + % Compute distance from (40bp,45bp), with x doubled + 45 sub dup mul exch + 40 sub dup mul 0.5 mul add sqrt + % exponential decay + dup mul neg 1.0005 exch exp 1.0 exch sub + % Compute distance from (70bp,70bp) from stored coordinate, scaled + 3 1 roll + 70 sub dup mul .5 mul exch + 70 sub dup mul add sqrt + % Decay + dup mul neg 1.002 exch exp 1.0 exch sub + % red component + 1.0 3 1 roll + } + \pgfuseshading{twospots} + +Inside the PostScript function ⟨type 4 function⟩ you cannot use colors +directly. Rather, you must push the color components on the stack. For +this, it is useful to call one of `\pgfshadecolortorgb`, +`\pgfshadecolortocmyk`, or `\pgfshadecolortogray` in the ⟨init code⟩: + + \pgfdeclarefunctionalshading[col1,col2,col3,col4]{bilinear interpolation} + {\pgfpointorigin}{\pgfpoint{100bp}{100bp}} + { + \pgfshadecolortorgb{col1}{\first}\pgfshadecolortorgb{col2}{\second} + \pgfshadecolortorgb{col3}{\third}\pgfshadecolortorgb{col4}{\fourth} + }{ + 100 div exch 100 div 2 copy % Calculate y/100 x/100. + neg 1 add exch neg 1 add % Calculate 1-y/100 1-x/100. + 3 1 roll 2 copy exch 5 2 roll 6 copy 6 copy % Set up stack. + \firstred mul exch \secondred mul add mul % Process red component. + 4 1 roll + \thirdred mul exch \fourthred mul add mul + add + 13 1 roll + \firstgreen mul exch \secondgreen mul add mul % Process green component. + 4 1 roll + \thirdgreen mul exch \fourthgreen mul add mul + add + 7 1 roll + \firstblue mul exch \secondblue mul add mul % Process blue component. + 4 1 roll + \thirdblue mul exch \fourthblue mul add mul + add + } + + \colorlet{col1}{blue} + \colorlet{col2}{yellow} + \colorlet{col3}{red} + \colorlet{col4}{green} + \pgfuseshading{bilinear interpolation} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarefunctionalshading" + }, + pgfdeclarehorizontalshading = { + arguments = { + {delimiters = {"[", "]"}, meta = "color list", optional = true}, + {meta = "shading name"}, + {meta = "shading height"}, + {meta = "color specification"} + }, + details = [[ +Declares a horizontal shading named ⟨shading name⟩ of the specified +⟨height⟩ with the specified colors. The width of the bar is deduced +automatically from the maximum dimension in the specification. + + \pgfdeclarehorizontalshading{myshadingA} + {1cm}{rgb(0cm)=(1,0,0); color(2cm)=(green); color(4cm)=(blue)} + \pgfuseshading{myshadingA} + +The effect of the ⟨color list⟩, which is a comma-separated list of +colors, is the following: Normally, when this list is empty, once a +shading has been declared, it becomes "frozen". This means that even if +you change a color that was used in the declaration of the shading later +on, the shading will not change. By specifying a ⟨color list⟩ you can +specify that the shading should be recalculated whenever one of the +colors listed in the list changes (this includes effects like color +mixins and `xcolor` color models). Thus, when you specify a ⟨color +list⟩, whenever the shading is used, PGF first converts the colors in +the list to tuples in the current `xcolor` color model using the current +values of the colors and taking any mixins and blends into account. If +the resulting tuples have not yet been used, a new shading is internally +created and used. Note that if the option ⟨color list⟩ is used, then no +shading is created until the first use of `\pgfuseshading`. In +particular, the colors mentioned in the shading need not be defined when +the declaration is given. + +When a shading is recalculated because of a change in the colors +mentioned in ⟨color list⟩, the complete shading is recalculated. Thus +even colors not mentioned in the list will be used with their current +values, not with the values they had upon declaration. + + \pgfdeclarehorizontalshading[mycolor]{myshadingB} + {1cm}{rgb(0cm)=(1,0,0); color(2cm)=(mycolor)} + \colorlet{mycolor}{green} + \pgfuseshading{myshadingB} + \colorlet{mycolor}{blue} + \pgfuseshading{myshadingB} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarehorizontalshading" + }, + pgfdeclareimage = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "image name"}, + {meta = "filename"} + }, + details = [[ +Declares an image, but does not paint anything. To draw the image, use +`\pgfuseimage{`⟨image name⟩`}`. The ⟨filename⟩ may not have an +extension. For PDF, the extensions `.pdf`, `.jpg`, and `.png` will +automatically tried. For PostScript, the extensions `.eps`, `.epsi`, and +`.ps` will be tried. + +The following options are possible: + +- `height=`⟨dimension⟩ sets the height of the image. If the width is + not specified simultaneously, the aspect ratio of the image is kept. + +- `width=`⟨dimension⟩ sets the width of the image. If the height is + not specified simultaneously, the aspect ratio of the image is kept. + +- `page=`⟨page number⟩ selects a given page number from a multipage + document. Specifying this option will have the following effect: + first, PGF tries to find a file named + + > ⟨filename⟩`.page`⟨page number⟩`.`⟨extension⟩ + + If such a file is found, it will be used instead of the originally + specified filename. If not, PGF inserts the image stored in + ⟨filename⟩`.`⟨extension⟩ and if a recent version of `pdflatex` is + used, only the selected page is inserted. For older versions of + `pdflatex` and for `dvips` the complete document is inserted and a + warning is printed. + +- `interpolate=`⟨true or false⟩ selects whether the image should be + "smoothed" when zoomed. False by default. + +- `mask=`⟨mask name⟩ selects a transparency mask. The mask must + previously be declared using `\pgfdeclaremask` (see below). This + option only has an effect for `pdf`. Not all viewers support + masking. + + + + \pgfdeclareimage[interpolate=true,height=1cm]{image1}{brave-gnu-world-logo} + \pgfdeclareimage[interpolate=true,width=1cm,height=1cm]{image2}{brave-gnu-world-logo} + \pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareimage" + }, + pgfdeclarelayer = { + arguments = {{meta = "name"}}, + details = [[ +This command declares a layer named ⟨name⟩ for later use. Mainly, this +will set up some internal bookkeeping. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarelayer" + }, + pgfdeclarelindenmayersystem = { + arguments = {{meta = "name"}, {meta = "specification"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarelindenmayersystem" + }, + pgfdeclaremask = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "mask name"}, + {meta = "filename"} + }, + details = [[ +Declares a transparency mask named ⟨mask name⟩ (called a *soft mask* in +the PDF specification). This mask is read from the file ⟨filename⟩. This +file should contain a grayscale image that is as large as the actual +image. A white pixel in the mask will correspond to "transparent", a +black pixel to "solid", and gray values correspond to intermediate +values. The mask must have a single "color channel". This means that the +mask must be a "real" grayscale image, not an RGB-image in which all +RGB-triples happen to have the same components. + +You can only mask images that are in a "pixel format". For drivers with +PDF output, these are `.jpg` and `.png` image files; you cannot mask +`.pdf` images in this way. Pixel images for the `dvips`+`ps2pdf` +workflow must be provided as `.eps` or `.ps` files. Also, again, the +mask file and the image file must have the same size. + +The following options may be given: + +- `matte=``{color components}` sets the so-called *matte* of the + actual image (strangely, this has to be specified together with the + mask, not with the image itself). The matte is the color that has + been used to preblend the image. For example, if the image has been + preblended with a red background, then ⟨color components⟩ should be + set to `{1 0 0}`. The default is `{1 1 1}`, which is white in the + rgb model. + + The matte is specified in terms of the parent's image color space. + Thus, if the parent is a grayscale image, the matte has to be set to + `{1}`. + + + + %% Draw a large colorful background + \pgfdeclarehorizontalshading{colorful}{5cm}{color(0cm)=(red); + color(2cm)=(green); color(4cm)=(blue); color(6cm)=(red); + color(8cm)=(green); color(10cm)=(blue); color(12cm)=(red); + color(14cm)=(green)} + \hbox{\pgfuseshading{colorful}\hskip-14cm\hskip1cm + \pgfimage[height=4cm]{brave-gnu-world-logo}\hskip1cm + \pgfimage[height=4cm]{brave-gnu-world-logo-mask}\hskip1cm + \pgfdeclaremask{mymask}{brave-gnu-world-logo-mask} + \pgfimage[mask=mymask,height=4cm,interpolate=true]{brave-gnu-world-logo}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclaremask" + }, + pgfdeclaremetadecorate = { + arguments = {{meta = "name"}, {meta = "initial state"}, {meta = "states"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclaremetadecorate" + }, + pgfdeclarepattern = { + arguments = {{meta = "config"}}, + details = [[ +This command is used to declare a new pattern. In contrast to the normal +patterns and in the spirit of `arrows.meta` this command takes a list of +keys and values to define the pattern. The following keys are available: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarepattern" + }, + pgfdeclarepatternformonly = { + arguments = { + {delimiters = {"[", "]"}, meta = "variables", optional = true}, + {meta = "name"}, + {meta = "bottom left"}, + {meta = "top right"}, + {meta = "tile size"}, + {meta = "code"} + }, + details = [[ +This command declares a new form-only pattern. The ⟨name⟩ is a name for +later reference. The two parameters ⟨lower left⟩ and ⟨upper right⟩ must +describe a bounding box that is large enough to encompass the complete +tile. + +The size of a tile is given by ⟨tile size⟩, that is, a tile is a +rectangle whose lower left corner is the origin and whose upper right +corner is given by ⟨tile size⟩. This might make you wonder why the +second and third parameters are needed. First, the bounding box might be +smaller than the tile size if the tile is larger than the picture on the +tile. Second, the bounding box might be bigger, in which case the +picture will "bleed" over the tile. + +The ⟨code⟩ should be PGF code than can be protocolled. It should not +contain any color code. + + \pgfdeclarepatternformonly{stars} + {\pgfpointorigin}{\pgfpoint{1cm}{1cm}} + {\pgfpoint{1cm}{1cm}} + { + \pgftransformshift{\pgfpoint{.5cm}{.5cm}} + \pgfpathmoveto{\pgfpointpolar{0}{4mm}} + \pgfpathlineto{\pgfpointpolar{144}{4mm}} + \pgfpathlineto{\pgfpointpolar{288}{4mm}} + \pgfpathlineto{\pgfpointpolar{72}{4mm}} + \pgfpathlineto{\pgfpointpolar{216}{4mm}} + \pgfpathclose% + \pgfusepath{fill} + } + \begin{tikzpicture} + \filldraw[pattern=stars] (0,0) rectangle (1.5,2); + \filldraw[pattern=stars,pattern color=red] + (1.5,0) rectangle (3,2); + \end{tikzpicture} + +The optional argument ⟨variables⟩ consists of a comma separated list of +macros, registers or keys, representing the parameters of the pattern +that may vary. If a variable is a key, then the full path name must be +used (specifically, it must start with `/`). As an example, a list might +look like the following: `\mymacro,\mydimen,/pgf/my key`. Note that +macros and keys should be "simple". They should only store values in +themselves. + +The effect of ⟨variables⟩, is the following: Normally, when this +argument is empty, once a pattern has been declared, it becomes +"frozen". This means that it is not possible to enlarge the pattern or +change the line width later on. By specifying ⟨variables⟩, no pattern is +actually created. Instead, the arguments are stored away (so the macros, +registers or keys do not have to be defined in advance). + +When the fill pattern is set, PGF checks if the pattern has already been +created with the ⟨variables⟩ set to their current values (PGF is usually +"smart enough" to distinguish between macros, registers and keys). If +so, this already-declared-pattern is used as the fill pattern. If not, a +new instance of the pattern (which will have a unique internal name) is +declared using the current values of ⟨variables⟩. These values are then +saved and the fill pattern set accordingly. + +The following shows an example of a pattern which varies according to +the values of the macro `\size`, the key `/tikz/radius`, and the TeX +dimension `\thickness`. + + \pgfdeclarepatternformonly[/tikz/radius,\thickness,\size]{rings} + {\pgfpoint{-0.5*\size}{-0.5*\size}} + {\pgfpoint{0.5*\size}{0.5*\size}} + {\pgfpoint{\size}{\size}} + { + \pgfsetlinewidth{\thickness} + \pgfpathcircle\pgfpointorigin{\pgfkeysvalueof{/tikz/radius}} + \pgfusepath{stroke} + } + \newdimen\thickness + \tikzset{ + radius/.initial=4pt, + size/.store in=\size, size=20pt, + thickness/.code={\thickness=#1}, + thickness=0.75pt + } + \begin{tikzpicture}[rings/.style={pattern=rings}] + \filldraw [rings, radius=2pt, size=6pt] (0,0) rectangle +(1.5,2); + \filldraw [rings, radius=2pt, size=8pt] (2,0) rectangle +(1.5,2); + \filldraw [rings, radius=6pt, thickness=2pt] (0,2.5) rectangle +(1.5,2); + \filldraw [rings, radius=8pt, thickness=4pt] (2,2.5) rectangle +(1.5,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarepatternformonly" + }, + pgfdeclarepatterninherentlycolored = { + arguments = { + {delimiters = {"[", "]"}, meta = "variables", optional = true}, + {meta = "name"}, + {meta = "lower left"}, + {meta = "upper right"}, + {meta = "tile size"}, + {meta = "code"} + }, + details = [[ +This command works like `\pgfdeclarepatternuncolored`, only the pattern +will have an inherent color. To set the color, you should use PGF's +color commands, not the `\color` command, since this fill is not +protocolled. + + \pgfdeclarepatterninherentlycolored{green stars} + {\pgfpointorigin}{\pgfpoint{1cm}{1cm}} + {\pgfpoint{1cm}{1cm}} + { + \pgfsetfillcolor{green!50!black} + \pgftransformshift{\pgfpoint{.5cm}{.5cm}} + \pgfpathmoveto{\pgfpointpolar{0}{4mm}} + \pgfpathlineto{\pgfpointpolar{144}{4mm}} + \pgfpathlineto{\pgfpointpolar{288}{4mm}} + \pgfpathlineto{\pgfpointpolar{72}{4mm}} + \pgfpathlineto{\pgfpointpolar{216}{4mm}} + \pgfpathclose% + \pgfusepath{stroke,fill} + } + \begin{tikzpicture} + \filldraw[pattern=green stars] (0,0) rectangle (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarepatterninherentlycolored" + }, + pgfdeclareplothandler = { + arguments = {{meta = "macro"}, {meta = "arguments"}, {meta = "configuration"}}, + details = [[ +This command creates a new plot handler that can subsequently be called +using the macro ⟨macro⟩. This macro take the arguments given in +⟨arguments⟩, which can be a list like `# 1# 2` if ⟨macro⟩ should be +invoked with two arguments. Here is a typical example: + + \pgfdeclareplothandler{\myhandler}{#1}{...} + ... + \myhandler{foo} + \pgfplotstreamstart + ... + \pgfplotstreamend + +The ⟨configuration⟩ is used to define the behavior of the handler. It is +a list of key--value pairs, where the following keys are allowed: + +- `start=`⟨code⟩. The ⟨code⟩ will be executed whenever + `\pgfplotstreamstart` is used while the handler ⟨macro⟩ is selected. + Inside the ⟨code⟩, you can use `# 1`, `# 2`, and so on to refer to + the parameters that were given to ⟨macro⟩: + + \pgfdeclareplothandler{\myhandler}{#1}{ + start = Hi #1., + end = Bye #1., + } + \myhandler{foo} + \pgfplotstreamstart + \pgfplotstreamend + \myhandler{bar} + \pgfplotstreamstart + \pgfplotstreamend + +- `end=`⟨code⟩ Works just like `start`. + +- `point=`⟨code⟩. The ⟨code⟩ will be executed whenever + `\pgfplotstreampoint` is used while the handler ⟨macro⟩ is in force. + Inside the ⟨code⟩, you can use `# 1`, `# 2`, and so on to refer to + the arguments give to ⟨macro⟩, while you can use `# # 1` to refer to + the argument given to `\pgfplotstreampoint` itself (this will be the + coordinate). + + \pgfdeclareplothandler{\myhandler}{#1}{ + point=\pgfpathcircle{##1}{#1} % ##1 is the coordinate, + % #1 the parameter for \myhandler + } + \begin{pgfpicture} + \myhandler{1pt} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0pt}{0pt}} + \pgfplotstreampoint{\pgfpoint{3pt}{3pt}} + \pgfplotstreampoint{\pgfpoint{6pt}{3pt}} + \pgfplotstreampoint{\pgfpoint{9pt}{0pt}} + \pgfplotstreamend + \pgfusepath{stroke} + \myhandler{3pt} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0pt}{0pt}} + \pgfplotstreampoint{\pgfpoint{9pt}{0pt}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{pgfpicture} + + The ⟨code⟩ will also be called for `\pgfplotstreampointoutlier` when + this command has been configured to `plot` the outliers. + +- `jump=`⟨code⟩ The ⟨code⟩ will be called whenever a jump has been + requested indirectly via an outlier point, and undefined point, or a + new data set (for each of which the command needs to be configured + to `jump`). As always, inside the ⟨code⟩ you can access `# 1` and so + on. + +- `special=`⟨code⟩ Causes ⟨code⟩ to be executed whenever + `\pgfplotstreamspecial``{something}` is used. Inside the ⟨code⟩, you + can access ⟨something⟩ via `# # 1` and the parameters of ⟨macro⟩ as + `# 1`, `# 2`, and so on. + +In addition to the above keys, there exist also "code macro versions" of +them: + +- `point macro=`⟨some macro⟩. Causes `\pgfplotstreampoint` to call + ⟨some macro⟩ directly (actually, `\pgf@plotstreampoint` is set to be + equal to ⟨some macro⟩). Inside the ⟨some macro⟩ you can use `# 1` to + access the coordinate passed to `\pgfplotstreampoint` and you can no + longer access the parameters passed to the original call to ⟨macro⟩ + that installed the handler. So, ⟨some macro⟩ must take exactly one + argument, namely `# 1`. + +- `special macro=`⟨some macro⟩. As `point macro`, only for specials. + +- `start macro=`⟨some macro⟩. Causes ⟨some macro⟩ to be executed at + the start. This macro, like the below ones, may not take any + parameters and will not have access to the parameters passed to the + original ⟨macro⟩. + +- `end macro=`⟨some macro⟩. As above. + +- `jump macro=`⟨some macro⟩. As above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareplothandler" + }, + pgfdeclareplotmark = { + arguments = {{meta = "plot mark name"}, {meta = "code"}}, + details = [[ +Declares a plot mark for later used with the `\pgfuseplotmark` command. + + \pgfdeclareplotmark{my plot mark} + {\pgfpathcircle{\pgfpoint{0cm}{1ex}}{1ex}\pgfusepathqstroke} + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfuseplotmark{my plot mark}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareplotmark" + }, + pgfdeclareradialshading = { + arguments = { + {delimiters = {"[", "]"}, meta = "color list", optional = true}, + {meta = "shading name"}, + {meta = "center point"}, + {meta = "color specification"} + }, + details = [[ +Declares a radial shading. A radial shading is a circle whose inner +color changes as specified by the color specification. Assuming that the +center of the shading is at the origin, the color of the center will be +the color specified for 0cm and the color of the border of the circle +will be the color for the maximum dimension given in the ⟨color +specified⟩. This maximum will also be the radius of the circle. If the +⟨center point⟩ is not at the origin, the whole shading inside the circle +(whose size remains exactly the same) will be distorted such that the +given center now has the color specified for 0cm. The effect of ⟨color +list⟩ is the same as for horizontal shadings. + + \pgfdeclareradialshading{sphere}{\pgfpoint{0.5cm}{0.5cm}}% + {rgb(0cm)=(0.9,0,0); + rgb(0.7cm)=(0.7,0,0); + rgb(1cm)=(0.5,0,0); + rgb(1.05cm)=(1,1,1)} + \pgfuseshading{sphere} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareradialshading" + }, + pgfdeclareshape = { + arguments = {{meta = "shape name"}, {meta = "shape specification"}}, + details = [[ +This command declares a new shape named ⟨shape name⟩. The shape name can +later be used in commands like `\pgfnode`. + +The ⟨shape specification⟩ is some TeX code containing calls to special +commands that are only defined inside the ⟨shape specification⟩ +(similarly to commands like `\draw` that are only available inside the +`{tikzpicture}` environment). + +Here is the code of the `coordinate` shape: + + \pgfdeclareshape{coordinate} + { + \savedanchor\centerpoint{% + \pgf@x=.5\wd\pgfnodeparttextbox% + \pgf@y=.5\ht\pgfnodeparttextbox% + \advance\pgf@y by -.5\dp\pgfnodeparttextbox% + } + \anchor{center}{\centerpoint} + \anchorborder{\centerpoint} + } + +The special commands are explained next. In the examples given for the +special commands a new shape will be constructed, which we might call +`simple rectangle`. It should behave like the normal rectangle shape, +only without bothering about the fine details like inner and outer +separations. The skeleton for the shape is the following. + + \pgfdeclareshape{simple rectangle}{ + ... + } + +The following example shows how a shape can be defined that relies +heavily on inheritance: + + \pgfdeclareshape{document}{ + \inheritsavedanchors[from=rectangle] % this is nearly a rectangle + \inheritanchorborder[from=rectangle] + \inheritanchor[from=rectangle]{center} + \inheritanchor[from=rectangle]{north} + \inheritanchor[from=rectangle]{south} + \inheritanchor[from=rectangle]{west} + \inheritanchor[from=rectangle]{east} + % ... and possibly more + \backgroundpath{% this is new + % store lower right in xa/ya and upper right in xb/yb + \southwest \pgf@xa=\pgf@x \pgf@ya=\pgf@y + \northeast \pgf@xb=\pgf@x \pgf@yb=\pgf@y + % compute corner of ``flipped page'' + \pgf@xc=\pgf@xb \advance\pgf@xc by-5pt % this should be a parameter + \pgf@yc=\pgf@yb \advance\pgf@yc by-5pt + % construct main path + \pgfpathmoveto{\pgfpoint{\pgf@xa}{\pgf@ya}} + \pgfpathlineto{\pgfpoint{\pgf@xa}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@ya}} + \pgfpathclose + % add little corner + \pgfpathmoveto{\pgfpoint{\pgf@xc}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}} + } + }\hskip-1.2cm + \begin{tikzpicture} + \node[shade,draw,shape=document,inner sep=2ex] (x) {Remark}; + \node[fill=yellow!80!black,draw,ellipse,double] + at ([shift=(-80:3cm)]x) (y) {Use Case}; + + \draw[dashed] (x) -- (y); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareshape" + }, + pgfdeclareverticalshading = { + arguments = { + {delimiters = {"[", "]"}, meta = "color list", optional = true}, + {meta = "shading name"}, + {meta = "shading width"}, + {meta = "color specification"} + }, + details = [[ +Declares a vertical shading named ⟨shading name⟩ of the specified +⟨width⟩. The height of the bar is deduced automatically. The effect of +⟨color list⟩ is the same as for horizontal shadings. + + \pgfdeclareverticalshading{myshadingC} + {4cm}{rgb(0cm)=(1,0,0); rgb(1.5cm)=(0,1,0); rgb(2cm)=(0,0,1)} + \pgfuseshading{myshadingC} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareverticalshading" + }, + pgfdecorateaftercode = { + details = [[ +Code executed as ⟨after code⟩, see the description of `\pgfdecorate`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecorateaftercode" + }, + pgfdecoratebeforecode = { + details = [[ +Code executed as ⟨before code⟩, see the description of `\pgfdecorate`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratebeforecode" + }, + pgfdecoratecurrentpath = { + arguments = {{meta = "name"}}, + details = [[ +Decorate the preexisting path with the decoration ⟨name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratecurrentpath" + }, + pgfdecoratedangle = { + details = [[ +The angle of the tangent to the decorated path at the *origin* of the +current segment. The transformation matrix applied at the beginning of a +state includes a rotation equivalent to this angle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedangle" + }, + pgfdecoratedcompleteddistance = { + details = [[ +The completed distance on the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedcompleteddistance" + }, + pgfdecoratedinputsegmentcompleteddistance = { + details = [[ +The completed distance on the current input segment of the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedinputsegmentcompleteddistance" + }, + pgfdecoratedinputsegmentlength = { + details = [[ +The length of the current input segment of the input path. "Current +input segment" refers to the input segment on which the current point +lies. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedinputsegmentlength" + }, + pgfdecoratedinputsegmentremainingdistance = { + details = [[ +The remaining distance on the current input segment of the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedinputsegmentremainingdistance" + }, + pgfdecoratedpath = { + details = [[ +The (total) input path (that is, the path created by the environment +contents). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedpath" + }, + pgfdecoratedpathlength = { + details = [[ +The length of the input path. If the input path consists of several +input segments, this number is the sum of the lengths of the input +segments. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedpathlength" + }, + pgfdecoratedremainingdistance = { + details = [[ +The remaining distance on the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedremainingdistance" + }, + pgfdecorateexistingpath = { + details = [[ +The preexisting path before the environment was entered. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecorateexistingpath" + }, + pgfdecoratepath = { + arguments = {{meta = "name"}, {meta = "path commands"}}, + details = [[ +Decorate the path described by ⟨path commands⟩ with the decoration +⟨name⟩. This is equivalent to + + \pgfdecorate{{name}{\pgfdecoratedpathlength} + {\pgfdecoratebeforecode}{\pgfdecorateaftercode}} + // the path commands. + \endpgfdecorate +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratepath" + }, + pgfdecorationpath = { + details = [[ +The output path. If the path is used, this macro contains only the last +unused part of the output path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecorationpath" + }, + pgfdvdeclarestylesheet = { + arguments = {{meta = "name"}, {meta = "keys"}}, + details = [[ +This command executes the ⟨keys⟩ with the path prefix +`/pgf/data visualization/style sheets/`⟨name⟩. The above definition of +the traffic light style sheet could be rewritten as follows: + + \pgfdvdeclarestylesheet{traffic light}{ + 1/.style={green!50!black}, + 2/.style={yellow!90!black}, + 3/.style={red!80!black}, + default style/.style={black} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdvdeclarestylesheet" + }, + pgferror = { + arguments = {{meta = "message"}}, + details = [[ +Stops the processing of the current document and prints out the +⟨message⟩. In LaTeX, this will be done using `\PackageError`, otherwise +`\errmessage` is used directly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgferror" + }, + pgfextra = { + arguments = {{meta = "code"}}, + details = [[ +This command may only be used inside a TikZ path. There it is used like +a normal path operation. The construction of the path is temporarily +suspended and the ⟨code⟩ is executed. Then, the path construction is +resumed. + + \newdimen\mydim + \begin{tikzpicture} + \mydim=1cm + \draw (0pt,\mydim) \pgfextra{\mydim=2cm} -- (0pt,\mydim); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfextra" + }, + pgfextractx = { + arguments = {{meta = "dimension"}, {meta = "point"}}, + details = [[ +Sets the TeX-⟨dimension⟩ to the $x$-coordinate of the point. + + \newdimen\mydim + \pgfextractx{\mydim}{\pgfpoint{2cm}{4pt}} + %% \mydim is now 2cm +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfextractx" + }, + pgfextracty = { + arguments = {{meta = "dimension"}, {meta = "point"}}, + details = [[ +Like `\pgfextractx`, except for the $y$-coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfextracty" + }, + pgffuncshadingcmyktogray = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top 4 elements on the stack from CMYK to grayscale. In +combination with the +texttt +textbackslash ifpgfshadingmodelgray conditional this macro can be used +to make functional shading declarations more portable across color +models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadingcmyktogray" + }, + pgffuncshadingcmyktorgb = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top 4 elements on the stack from CMYK to RGB. In combination +with the +texttt +textbackslash ifpgfshadingmodelrgb conditional this macro can be used to +make functional shading declarations more portable across color models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadingcmyktorgb" + }, + pgffuncshadinggraytocmyk = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top element on the stack from grayscale to CMYK. In +combination with the +texttt +textbackslash ifpgfshadingmodelcmyk conditional this macro can be used +to make functional shading declarations more portable across color +models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadinggraytocmyk" + }, + pgffuncshadinggraytorgb = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top element on the stack from grayscale to RGB. In +combination with the +texttt +textbackslash ifpgfshadingmodelrgb conditional this macro can be used to +make functional shading declarations more portable across color models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadinggraytorgb" + }, + pgffuncshadingrgbtocmyk = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top 3 elements on the stack from RGB to CMYK. In combination +with the +texttt +textbackslash ifpgfshadingmodelcmyk conditional this macro can be used +to make functional shading declarations more portable across color +models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadingrgbtocmyk" + }, + pgffuncshadingrgbtogray = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top 3 elements on the stack from RGB to grayscale. In +combination with the +texttt +textbackslash ifpgfshadingmodelgray conditional this macro can be used +to make functional shading declarations more portable across color +models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadingrgbtogray" + }, + pgfgaliasid = { + arguments = {{meta = "1"}, {meta = "2"}}, + details = [[ +Like `\pgfaliasid`, only the alias is set globally. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgaliasid" + }, + pgfgdaddspecificationhook = { + arguments = {{meta = "code"}}, + details = [[ +This command adds the ⟨code⟩ to the code that is executed whenever a +graph drawing scope starts. For instance, the TikZ library +`graphdrawing` uses this macro to add some ⟨code⟩ that will redirect the +`edge` and `edge from parent` path commands to `\pgfgdedge`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdaddspecificationhook" + }, + pgfgdbegineventgroup = { + arguments = {{meta = "parameter"}}, + details = [[ +Starts an event group. This just means that an `Event` of kind `begin` +is created with the given ⟨parameter⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdbegineventgroup" + }, + pgfgdbeginlayout = { + details = [[ +This command first starts a new TeX scope and then informs the display +layer that a new (sub)layout should be started. For each graph there may +be a hierarchy of layouts, each of which contains a certain number of +vertices and edges. This hierarchy is created through calls to this +macros and the corresponding calls of `\pgfgdendlayout`. For each graph +drawing scope there has to be exactly one main layout that encompasses +all nodes and edges and also all sublayouts. Thus, after a graph drawing +scope has been opened, a layout scope also needs to be opened almost +immediately. + +For each layout created via this macro, a graph drawing algorithm will +be run later on the subgraph of all nodes that make up the layout. Which +algorithm is run for the layout is dictated by which layout key (one of +the `... layout` keys) is "in force" when the macro is called. Thus, +using a layout key for selecting an algorithm must always be done +*before* the layout is started. (However, see the discussion of layout +keys in the next subsection for more details on what really happens.) + +A vertex can be part of several layouts, either because they are nested +or because they overlap (this happens when a node is later on added to +another layout by calling `\pgfgdsetlatenodeoption`). This means that it +is not immediately obvious how conflicts arising from the different ways +different algorithms "would like to place nodes" should be resolved. The +method for this resolving is detailed in Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdbeginlayout" + }, + pgfgdbeginscope = { + details = [[ +This macro starts a TeX scope inside which the following things happen: + +1. The display layer method `beginGraphDrawingScope` is called, which + created a new graph drawing scope inside the graph drawing system + and places it on top of an internal stack. From now on, all + subsequent interface calls will refer to this scope until + `\pgfgdendscope` is called, which will pop the scope once more. + +2. Inside the TeX scope, nodes are not placed immediately. Rather, + `\pgfpositionnodelater`, see Section ??, is used to call + `InterfaceToDisplay.createVertex` for all nodes created inside the + scope. This will cause them to be put inside some internal table. + +3. Some additional ⟨code⟩ is executed, which has been set using the + following command: + +4. `\pgftransformreset` is called. + +5. The following TeX-if is set to true: + + Will be true inside a graph drawing scope. + +The above has a number of consequences for what can happen inside a +graph drawing scope: + +- Since nodes are not actually created before the end of the scope, + you cannot reference these nodes. Thus, you cannot write + + \tikz [spring layout] { + \node (a) {a}; + \node (b) {b}; + \draw (a) -- (b); + } + + The problem is that we cannot connect `(a)` and `(b)` via a straight + line since these nodes do not exist at that point (they are + available only deeply inside the Lua). + +- In order to create edges between nodes inside a graph drawing scope, + you need to call the `\pgfgdedge` command, described below. + +Additionally, when TikZ is used, the following things also happen: + +- If the `graphs` library has been loaded, the default positioning + mechanisms of this library are switched off, leaving the positioning + to the graph drawing engine. Also, when an edge is created by the + `graphs` library, this is signalled to the `graphdrawing` library. + (To be more precise: The keys `new ->` and so on are redefined so + that they call `\pgfgdedge` instead of creating an edge. + +- The `edge` path command is modified so that it also calls + `\pgfgdedge` instead of immediately creating any edges. + +- The `edge from parent` path command is modified so that is also + calls `\pgfgdedge`. + +- The keys `append after command` and `prefix after command` keys are + modified so that they are executed only via `late options` when the + node has "reached its final parking position". + +Note that inside a graph drawing scope you first have to open a (main) +layout scope (using the `\pgfgdbeginlayout` command described later on) +before you can add nodes and edges to the scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdbeginscope" + }, + pgfgdedge = { + arguments = { + {meta = "first node"}, + {meta = "second node"}, + {meta = "edge direction"}, + {meta = "edge options"}, + {meta = "edge nodes"} + }, + details = [[ +This command is used to tell the graph drawing engine that there is an +edge between ⟨first node⟩ and ⟨second node⟩ in your graph. The "kind" of +connection is indicated by ⟨direction⟩, which may be one of the +following: + +- `->` indicates a directed edge (also known as an arc) from ⟨first + node⟩ to ⟨second node⟩. + +- `–` indicates an undirected edge between ⟨first node⟩ and ⟨second + node⟩, + +- `<-` indicates a directed edge from ⟨second node⟩ to ⟨first node⟩, + but with the "additional hint" that this is a "backward" edge. A + graph drawing algorithm may or may not take this hint into account. + +- `<->` indicates a bi-directed edge between ⟨first node⟩ and ⟨second + node⟩. + +- `-!-` indicates that the edge from ⟨first node⟩ to ⟨second node⟩ is + "missing". + +Note that in all cases, the syntactic digraph will contain an arc from +⟨first node⟩ to ⟨second node⟩, regardless of the value of ⟨direction⟩. +The ⟨direction⟩ is "just" a "semantic annotation". + +The parameters ⟨edge options⟩ and ⟨edge nodes⟩ are a bit more tricky. +When an edge between two vertices of a graph is created via +`\pgfgdedge`, nothing is actually done immediately. After all, without +knowing the final positions of the nodes ⟨first node⟩ and ⟨second node⟩, +there is no way of creating the actual drawing commands for the edge. +Thus, the actual drawing of the edge is done only when the graph drawing +algorithm is done (namely in the macro `\pgfgdedgecallback`, see later). + +Because of this "delayed" drawing of edges, options that influence the +edge must be retained until the moment when the edge is actually drawn. +Parameters ⟨edge options⟩ and ⟨edge nodes⟩ store such options. + +Let us start with ⟨edge options⟩. This parameter should be set to a list +of key--value pairs like + + /tikz/.cd, color=red, very thick, orient=down + +Some of these options may be of interest to the graph drawing algorithm +(like the last option) while others will only be important during the +drawing of edge (like the first option). The options that are important +for the graph drawing algorithm must be pushed onto the graph drawing +system's option stack. + +The tricky part is that options that are of interest to the graph +drawing algorithm must be executed *before* the algorithm starts, but +the options as a whole are usually only executed during the drawing of +the edges, which is *after* the algorithm has finished. To overcome this +problem, the following happens: + +The options in ⟨edge options⟩ are executed "tentatively" inside +`\pgfgdedge`. However, this execution is done in a "heavily guarded +sandbox" where all effects of the options (like changing the color or +the line width) do not propagate beyond the sandbox. Only the changes of +the graph drawing edge parameters leave the sandbox. These parameters +are then passed down to the graph drawing system. + +Later, when the edge is drawn using `\pgfgdedgecallback`, the options +⟨edge options⟩ are available once more and then they are executed +normally. + +Note that when the options in ⟨edge options⟩ are executed, no path is +preset. Thus, you typically need to start it with, say, `/tikz/.cd`. +Also note that the sandbox is not perfect and changing global values +will have an effect outside the sandbox. Indeed, "putting things in a +sandbox" just means that the options are executed inside a TeX scope +inside an interrupted path inside a TeX box that is thrown away +immediately. + +The text in ⟨edge nodes⟩ is some "auxiliary" text that is simply stored +away and later directed to `\pgfgdedgecallback`. This is used for +instance by TikZ to store its node labels. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdedge" + }, + pgfgdendeventgroup = { + details = [[ +Ends an event group. This is done by adding an event of kind `end` +without any parameters to the event string. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdendeventgroup" + }, + pgfgdendlayout = { + details = [[ +This command ends the TeX scope of the current layout. Once closed, no +nodes or edges can be added to a layout. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdendlayout" + }, + pgfgdendscope = { + details = [[ +This macro is used to end a graph drawing scope. It must be given on the +same TeX grouping level as the corresponding `\pgfgdbeginscope`. When +the macro is called, it triggers a lot of new calls: + +1. The special treatment of newly created boxes is ended. Nodes are + once more created normally. + +2. The effects of the ⟨code⟩ that was inserted via the specification + hook command also ends (provided it had no global effects). + +3. We call `InterfaceToDisplay.runGraphDrawingAlgorithm`. This will + cause the algorithm(s) for the graph to be executed (since a graph + can have sublayouts, several algorithms may be run). See Section ?? + below. + +4. Next, we call `InterfaceToDisplay.endGraphDrawingScope`. This causes + all nodes that were intercepted during the graph drawing scope to be + reinserted into the output stream at the positions that were + computed for them. Also, for each edge that was requested via + `\pgfgdedge`, the callback macro is called (see below). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdendscope" + }, + pgfgdevent = { + arguments = {{meta = "kind"}, {meta = "parameter"}}, + details = [[ +Calls `createEvent` of the graph drawing system's interface class. This +creates a new `Event` object on the Lua layer whose `kind` field is set +to ⟨kind⟩ and the `parameters` field to ⟨parameter⟩. You must be inside +a graph drawing scope to use this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdevent" + }, + pgfgdeventgroup = { + arguments = {{meta = "parameters"}}, + details = [[ +Starts an event group just like `\pgfgdbegineventgroup`, but adds a +corresponding closing `end` event at the end of the current TeX group +(using `\aftergroup`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdeventgroup" + }, + pgfgdsetedgecallback = { + arguments = {{meta = "macro"}}, + details = [[ +This command allows you to change the ⟨macro⟩ that gets called form +inside the graph drawing system at the end of the creation of a graph, +when the nodes have been positioned. The ⟨macro⟩ will be called once for +each edge with the following parameters: + +> ⟨macro⟩`{first node}``{second node}``{direction}``{edge options}``{edge nodes}` +> `{algorithm-generated options}``{bend information}``{animations}` + +The first five parameters are the original values that were passed down +to the `\pgfgdedge` command. + +The ⟨algorithm-generated options⟩ have been "computed by the algorithm". +For instance, an algorithm might have determined, say, flow capacities +for edges and it might now wish to communicate this information back to +the upper layers. These options should be executed with the path +`/graph drawing`. + +The parameter ⟨bend information⟩ contains algorithmically-computed +information concerning how the edge should bend. This will be a text +like `(10pt,20pt)–(30pt,40pt)` in TikZ-syntax and may include the path +commands `–`, `..` (followed by Bézier coordinates), and `–cycle`. + +The parameter ⟨animations⟩ contains algorithmically-generated animation +commands (calls to `\pgfanimateattribute`. The `whom` will be set to +`pgf@gd`. + +The default ⟨macro⟩ simply draws a line between the nodes. When the +`graphdrawing` library of the TikZ layer is loaded, a more fancy ⟨macro⟩ +is used that takes all of the parameters into account. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdsetedgecallback" + }, + pgfgdsetlatenodeoption = { + arguments = {{meta = "node name"}}, + details = [[ +This command can only be called when the node named ⟨node name⟩ has +already been created inside the current graph drawing scope. The effect +of calling this macro will be that all options currently on the graph +drawing system's option stack will be added to the node's option, +possibly overwriting the original option settings. Furthermore, the node +will become part of all layouts currently on the option stack. This +means that you can use this command to add a node to several layouts +that are not included in one another. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdsetlatenodeoption" + }, + pgfgdsetrequestcallback = { + arguments = {{meta = "macro"}}, + details = [[ +This command sets up ⟨macro⟩ as the macro that is called whenever a +layout key "requests" that a layout and, possibly, a graph drawing scope +is opened. When ⟨macro⟩ is called, it gets two parameters, the ⟨begin +code⟩ and the ⟨end code⟩. In addition to whatever setup the ⟨macro⟩ +would like to do, it should execute the ⟨begin code⟩ at the beginning of +a TeX scope (the code will open graph drawing and layout scopes) and the +⟨end code⟩ at the end of the same TeX scope. + +The need for this slightly strange macro arises from the fact that in +TikZ we often write things like `[spring layout,node sep=2cm]`. The +point is that when the `spring layout` key is executed, we do *not* wish +to open a layout scope immediately. Rather, this should happen only +after the option `nodes sep=2cm` has been executed. For this reason, +TikZ sets up a special ⟨macro⟩ that "delays" the execution of the ⟨begin +code⟩ until the end of the opening of the next scope. + +Because of this, in TikZ layout keys can only be used as an option when +a TikZ scope is started. Thus, you can pass them to `\tikz`, to +`{tikzpicture}`, to `\scoped`, to `{scope}`, to `graph`, and to +`{graph}`. For instance, the `tree layout` option can be used in the +following ways: + + \tikz [tree layout] \graph {1 -> {b,c}}; + \tikz \graph [tree layout] {2 -> {b,c}}; + \tikz \path graph [tree layout] {3 -> {b,c}}; + + \begin{tikzpicture}[tree layout] + \graph {4 -> {b,c}}; + \end{tikzpicture} + + \begin{tikzpicture} + \scoped [tree layout] \graph {5 -> {b,c}}; + + \begin{scope}[tree layout, xshift=1.5cm] + \graph {6 -> {b,c}}; + \end{scope} + \end{tikzpicture} + +You can *not* use layout keys with a single node or on a path. In +particular, to typeset a tree given in the `child` syntax somewhere +inside a `{tikzpicture}`, you must prefix it with the `\scoped` command: + + \begin{tikzpicture} + \scoped [tree layout] + \node {root} + child { node {left child} } + child { node {right child} }; + \end{tikzpicture} + +Naturally, the above could have been written more succinctly as + + \tikz [tree layout] + \node {root} + child { node {left child} } + child { node {right child} }; + +Or even more succinctly: + + \tikz \graph [tree layout] { root -- {left child, right child} }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdsetrequestcallback" + }, + pgfgdsubgraphnode = { + arguments = {{meta = "name"}, {meta = "node options"}, {meta = "node text"}}, + details = [[ +A subgraph node is a node that "surrounds" the nodes of a subgraph. The +special property of a subgraph node opposed to a normal node is that it +is created only after the subgraph has been laid out. However, the +difference to a collection like `hyper` is that the node is available +immediately as a normal node in the sense that you can connect edges to +it. + +What happens internally is that subgraph nodes get "registered" +immediately both on the PGF level and on the Lua level, but the actual +node is only created inside the layout pipeline using a callback. The +actual node creation happens when the innermost layout in which the +subgraph node is declared has finished. + +When you create a subgraph node using this macro, you also start a +collection (of an internal kind) that stores the subgraph. All following +nodes in the current TeX scope will become part of this collection. + +The ⟨name⟩ is the node name by which you can refer to this node in the +following. The ⟨node options⟩ are normal PGF options (like `red` or +`draw` or `circle`) that will influence the appearance when it is +created later on. The ⟨node text⟩ is the text that will be passed to +`\pgfnode` upon creation of the node. + +See `InterfaceToDisplay.pushSubgraphVertex` for more details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdsubgraphnode" + }, + pgfgetlastxy = { + arguments = {{meta = "macro for $x$"}, {meta = "macro for $y$"}}, + details = [[ +Stores the most recently used $(x,y)$ coordinates into two macros. + + \pgfpoint{2cm}{4cm} + \pgfgetlastxy{\macrox}{\macroy} + Macro $x$ is `\macrox' and macro $y$ is `\macroy'. + +Since $(x,y)$ coordinates are usually assigned globally, it is safe to +use this command after path operations. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgetlastxy" + }, + pgfgettransform = { + arguments = {{meta = "macro"}}, + details = [[ +This command will (locally) define ⟨macro⟩ to a representation of the +current coordinate transformation matrix. This matrix can later on be +reinstalled using `\pgfsettransform`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgettransform" + }, + pgfgettransformentries = { + arguments = { + {meta = "macro for a"}, + {meta = "macro for b"}, + {meta = "macro for c"}, + {meta = "macro for d"}, + {meta = "macro for shift x"}, + {meta = "macro for shift y"} + }, + details = [[ +This command is similar to `\pgfgettransform` except that it stores the +current coordinate transformation matrix in a set of six macros. + +The matrix can later on be reinstalled using `\pgfsettransformentries`. +Furthermore, all these macros (or just a few of them) can be used as +arguments for `\pgftransformcm`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgettransformentries" + }, + pgfhorizontaltransformationadjustment = { + details = [[ +When you scale the length of a horizontal line by this factor in the +current transformation, you compensate for the scaling. Formally, it is +$1/\\texttt{\textbackslash mathit\{transform\}(1,0)\textbackslash }_2$, +where $\mathit{transform}$ applies the current transformations matrix to +the given number. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (2,2); + \begin{scope}[xscale=2,thick] + \draw [red] (1,1) -- ++(1,0); + + \pgftransformationadjustments + \draw [blue] (1,0) -- ++(\pgfhorizontaltransformationadjustment,0); + \end{scope} + \end{tikzpicture} + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (2,2); + \begin{scope}[xscale=2,thick,rotate=90] + \draw [red] (1,1) -- ++(1,0); + + \pgftransformationadjustments + \draw [blue] (1,0) -- ++(\pgfhorizontaltransformationadjustment,0); + \end{scope} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfhorizontaltransformationadjustment" + }, + pgfidrefnextuse = { + arguments = {{meta = "macro"}, {meta = "name"}}, + details = [[ +This command assigns a system layer identifier (the identifier returned +by `\pgfsys@new@id`) to the ⟨macro⟩, namely the one that will be used +the *next* time `\pgfuseid` is used. You use this command for "forward +referencing". + +A typical use case is the following: A key like `whom` for animations +uses this command to get the system identifier that will be used for a +future object. Then, this identifier can be passed to system layer +commands like `\pgfsys@animation@whom`. + +Note that the "next" use need not be on the same page (or there may not +even be any use at all), in which case the reference will not refer to +any object. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfidrefnextuse" + }, + pgfidrefprevuse = { + arguments = {{meta = "macro"}, {meta = "name"}}, + details = [[ +Works like `\pgfidrefnextuse`, only it references the most recent +*previous* use of the ⟨name⟩. As for `\pgfidrefnextuse`, the most recent +use need not be on the same page. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfidrefprevuse" + }, + pgfifidreferenced = { + arguments = {{meta = "name"}, {meta = "then code"}, {meta = "else code"}}, + details = [[ +If ⟨name⟩ has been referenced, ⟨then code⟩ is executed, otherwise ⟨else +code⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfifidreferenced" + }, + pgfimage = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "filename"} + }, + details = [[ +Declares the image under the name `pgflastimage` and immediately uses +it. You can "save" the image for later usage by invoking +`\pgfaliasimage` on `pgflastimage`. + + \begin{colormixin}{25!white} + \begin{pgfpicture} + \pgftext[at=\pgfpoint{1cm}{5cm},left,base] + {\pgfimage[interpolate=true,width=1cm,height=1cm]{brave-gnu-world-logo}} + \pgftext[at=\pgfpoint{1cm}{3cm},left,base] + {\pgfimage[interpolate=true,width=1cm]{brave-gnu-world-logo}} + \pgftext[at=\pgfpoint{1cm}{1cm},left,base] + {\pgfimage[interpolate=true,height=1cm]{brave-gnu-world-logo}} + + \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} + \end{pgfpicture} + \end{colormixin} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfimage" + }, + pgfintersectionofpaths = { + arguments = {{meta = "path 1"}, {meta = "path 2"}}, + details = [[ +This command finds the intersection points on the paths ⟨path 1⟩ and +⟨path 2⟩. The number of intersection points ("solutions") that are found +will be stored, and each point can be accessed afterward. The code for +⟨path 1⟩ and ⟨path 2⟩ is executed within a TeX group and so can contain +transformations (which will be in addition to any existing +transformations). The code should not use the path in any way, unless +the path is saved first and restored afterward. PGF will regard +solutions as "a bit special", in that the points returned will be +"absolute" and unaffected by any further transformations. + + \begin{pgfpicture} + \pgfintersectionofpaths + { + \pgfpathellipse{\pgfpointxy{0}{0}}{\pgfpointxy{1}{0}}{\pgfpointxy{0}{2}} + \pgfgetpath\temppath + \pgfusepath{stroke} + \pgfsetpath\temppath + } + { + \pgftransformrotate{-30} + \pgfpathrectangle{\pgfpointorigin}{\pgfpointxy{2}{2}} + \pgfgetpath\temppath + \pgfusepath{stroke} + \pgfsetpath\temppath + } + \foreach \s in {1,...,\pgfintersectionsolutions} + {\pgfpathcircle{\pgfpointintersectionsolution{\s}}{2pt}} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfintersectionofpaths" + }, + pgfintersectionsolutions = { + details = [[ +After using the `\pgfintersectionofpaths` command, this TeX-macro will +indicate the number of solutions found. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfintersectionsolutions" + }, + pgfintersectionsortbyfirstpath = { + details = [[ +Using this command will mean the solutions will be sorted along ⟨path +1⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfintersectionsortbyfirstpath" + }, + pgfintersectionsortbysecondpath = { + details = [[ +Using this command will mean the solutions will be sorted along ⟨path +2⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfintersectionsortbysecondpath" + }, + pgfkeys = { + arguments = {{meta = "key list"}}, + details = [[ +The ⟨key list⟩ should be a list of key--value pairs, separated by +commas. A key--value pair can have the following two forms: +⟨key⟩`=`⟨value⟩ or just ⟨key⟩. Any spaces around the ⟨key⟩ or around the +⟨value⟩ are removed. It is permissible to surround both the ⟨key⟩ or the +⟨value⟩ in curly braces, which are also removed. Especially putting the +⟨value⟩ in curly braces needs to be done quite often, namely whenever +the ⟨value⟩ contains an equal-sign or a comma. + +The key--value pairs in the list are handled in the order they appear. +How this handling is done, exactly, is described in the rest of this +section. + +If a ⟨key⟩ is a partial key, the current value of the default path is +prefixed to the ⟨key⟩ and this "upgraded" key is then used. The default +path is just the root path `/` when the first key is handled, but it may +change later on. At the end of the command, the default path is reset to +the value it had before this command was executed. + +Calls of this command may be nested. Thus, it is permissible to call +`\pgfkeys` inside the code that is executed for a key. Since the default +path is restored after a call of `\pgfkeys`, the default path will not +change when you call `\pgfkeys` while executing code for a key (which is +exactly what you want). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeys" + }, + pgfkeysactivatefamilies = { + arguments = {{meta = "family list"}, {meta = "deactivate macro name"}}, + details = [[ +Activates each family in ⟨family list⟩ and creates a macro ⟨deactivate +macro name⟩ which deactivates each family in ⟨family list⟩. + + \pgfkeysactivatefamilies{/family 1,/family 2,/family 3}{\deactivatename} + \pgfkeysfiltered{foo,bar} + \deactivatename +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysactivatefamilies" + }, + pgfkeysactivatefamiliesandfilteroptions = { + arguments = {{meta = "family list"}, {meta = "key--value-list"}}, + details = [[ +A simple shortcut macro which activates any family in the comma +separated `{family list}`, invokes `\pgfkeysfiltered`⟨key--value-list⟩ +and deactivates the families afterwards. + +Please note that you will need to install a family key filter, otherwise +family activation has no effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysactivatefamiliesandfilteroptions" + }, + pgfkeysactivatefamily = { + arguments = {{meta = "family name"}}, + details = [[ +Equivalent to `\pgfkeys{`⟨family name⟩`/.activate family}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysactivatefamily" + }, + pgfkeysactivatesinglefamilyandfilteroptions = { + arguments = {{meta = "family name"}, {meta = "key--value-list"}}, + details = [[ +A shortcut macro which activates a single family and invokes +`\pgfkeysfiltered`. + +Please note that you will need to install a family key filter, otherwise +family activation has no effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysactivatesinglefamilyandfilteroptions" + }, + pgfkeysalso = { + arguments = {{meta = "key list"}}, + details = [[ +This command has exactly the same effect as `\pgfkeys`, only the default +path is not modified before or after the keys are being set. This +command is mainly intended to be called by the code that is being +processed for a key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysalso" + }, + pgfkeysalsofiltered = { + arguments = {{meta = "key--value-list"}}, + details = [[ +This command works as `\pgfkeysfiltered`, but it does not change the +current default path. See the documentation of `\pgfkeysalso` for more +details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysalsofiltered" + }, + pgfkeysalsofilteredfrom = { + arguments = {{meta = "macro"}}, + details = [[ +A variant of `\pgfkeysalsofiltered` which loads its key list from +`{macro}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysalsofilteredfrom" + }, + pgfkeysalsofrom = { + arguments = {{meta = "macro"}}, + details = [[ +A variant of `\pgfkeysalso` which loads its key list from `{macro}`. + +It is useful in conjunction with the +`/pgf/key filter handlers/append filtered to=`⟨macro⟩ handler. + +The following example uses the same settings as in the intro section ??. + + \pgfkeys{/pgf/key filter handlers/append filtered to/.install key filter handler=\remainingoptions} + \def\remainingoptions{} + \pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, + /my group/B=b, /my group/C=c, /tikz/color=blue, /my group/A3=a3} + + Remaining: `\remainingoptions'. + \pgfkeysalsofrom{\remainingoptions} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysalsofrom" + }, + pgfkeysdeactivatefamily = { + arguments = {{meta = "family name"}}, + details = [[ +Equivalent to `\pgfkeys{`⟨family name⟩`/.deactivate family}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysdeactivatefamily" + }, + pgfkeysdef = { + arguments = {{meta = "key"}, {meta = "code"}}, + details = [[ +This command temporarily defines a TeX-macro with the argument list +`# 1\pgfeov` and then lets ⟨key⟩`/.@cmd` be equal to this macro. The net +effect of all this is that you have then set up code for the key ⟨key⟩ +so that when you write `\pgfkeys{`⟨key⟩`=`⟨value⟩`}`, then the ⟨code⟩ is +executed with all occurrences of `# 1` in ⟨code⟩ being replaced by +⟨value⟩. (This behavior is quite similar to the `\define@key` command of +`keyval` and `xkeyval`). + + \pgfkeysdef{/my key}{#1, #1.} + \pgfkeys{/my key=hello} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysdef" + }, + pgfkeysdefargs = { + arguments = {{meta = "key"}, {meta = "argument pattern"}, {meta = "code"}}, + details = [[ +This command works like `\pgfkeysdefnargs`, but it allows you to provide +an arbitrary ⟨argument pattern⟩ rather than just a number of arguments. + + \pgfkeysdefargs{/my key}{#1+#2}{\def\a{#1}\def\b{#2}} + \pgfkeys{/my key=hello+world} + + |\a| is \a, |\b| is \b. + +Note that `\pgfkeysdefnargs` is *better* when it comes to simple +argument *counts*[1]. + +[1] When the resulting keys are used, the `defnargs` variant allows +spaces between arguments whereas the `defargs` variant does not; it +considers the spaces as part of the argument. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysdefargs" + }, + pgfkeysdefnargs = { + arguments = {{meta = "key"}, {meta = "argument count"}, {meta = "code"}}, + details = [[ +This command works like `\pgfkeysdef`, but it allows you to provide an +arbitrary ⟨argument count⟩ between $0$ and $9$ (inclusive). + + \pgfkeysdefnargs{/my key}{2}{\def\a{#1}\def\b{#2}} + \pgfkeys{/my key= + {hello} + {world}} + + |\a| is `\a', |\b| is `\b'. + +The resulting key will expect exactly `{argument count}` arguments. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysdefnargs" + }, + pgfkeysedef = { + arguments = {{meta = "key"}, {meta = "code"}}, + details = [[ +This command works like `\pgfkeysdef`, but it uses `\edef` rather than +`\def` when defining the key macro. If you do not know the difference +between the two, then you will not need this command; and if you know +the difference, then you will know when you need this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysedef" + }, + pgfkeysedefargs = { + arguments = {{meta = "key"}, {meta = "argument pattern"}, {meta = "code"}}, + details = [[ +The `\edef` version of `\pgfkeysdefargs`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysedefargs" + }, + pgfkeysedefnargs = { + arguments = {{meta = "key"}, {meta = "argument count"}, {meta = "code"}}, + details = [[ +The `\edef` version of `\pgfkeysdefnargs`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysedefnargs" + }, + pgfkeysevalkeyfilterwith = { + arguments = {{meta = "full key"}, {literal = "="}, {meta = "filter arguments"}}, + details = [[ +Evaluates a fully qualified key filter ⟨full key⟩ with argument(s) +⟨filter arguments⟩. + + \pgfkeysevalkeyfilterwith{/pgf/key filters/equals=/tikz} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysevalkeyfilterwith" + }, + pgfkeysfiltered = { + arguments = {{meta = "key--value-list"}}, + details = [[ +Processes all options in exactly the same way as +`\pgfkeys``{key–value-list}`, but a key filter is considered as soon as +key identification is complete. + +The key filter tells `\pgfkeysfiltered` whether it should continue to +apply the current option (return value is 'true') or whether something +different shall be done (filter returns 'false'). + +There is exactly one key filter in effect, and it is installed by the +`.install key filter` handler or by `\pgfkeysinstallkeyfilter`. + +If the key filter returns 'false', a unique key filter handler gets +control. This handler is installed by the `.install key filter handler` +method and has access to the key's full name, value and (possibly) path. + +Key filtering applies to any (possibly nested) call to `\pgfkeys`, +`\pgfkeysalso`, `\pgfqkeys` and `\pgfqkeysalso` during the evaluation of +`{key–value-list}`. It does *not* apply to routines like +`\pgfkeyssetvalue` or `\pgfkeysgetvalue`. Furthermore, keys belonging to +`/errors` are always processed. Key filtering routines can't be nested: +you can't combine different key filters automatically. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysfiltered" + }, + pgfkeysgetfamily = { + arguments = {{meta = "full key"}, {meta = "resultmacro"}}, + details = [[ +Returns the family associated to a ⟨full key⟩ into macro ⟨resultmacro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysgetfamily" + }, + pgfkeysgetvalue = { + arguments = {{meta = "full key"}, {meta = "macro"}}, + details = [[ +Retrieves the tokens stored in the ⟨full key⟩ and lets ⟨macro⟩ be equal +to these tokens. If the key has not been set, the ⟨macro⟩ will be equal +to `\relax`. + + \pgfkeyssetvalue{/my family/my key}{Hello, world!} + \pgfkeysgetvalue{/my family/my key}{\helloworld} + \helloworld +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysgetvalue" + }, + pgfkeysifdefined = { + arguments = {{meta = "full key"}, {meta = "if"}, {meta = "else"}}, + details = [[ +Checks whether this key was previously set using either +`\pgfkeyssetvalue` or `\pgfkeyslet`. If so, the code in ⟨if⟩ is +executed, otherwise the code in ⟨else⟩. + +This command will use eTeX's `\ifcsname` command, if available, for +efficiency. This means, however, that it may behave differently for +TeX and for eTeX when you set keys to `\relax`. For this reason you +should not do so. + + \pgfkeyssetvalue{/my family/my key}{Hello, world!} + \pgfkeysifdefined{/my family/my key}{yes}{no} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysifdefined" + }, + pgfkeysiffamilydefined = { + arguments = {{meta = "family"}, {meta = "true case"}, {meta = "false case"}}, + details = [[ +Checks whether the full key ⟨family⟩ is a family and executes either +⟨true case⟩ or ⟨false case⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysiffamilydefined" + }, + pgfkeysinstallkeyfilter = { + arguments = {{meta = "full key"}, {meta = "optional arguments"}}, + details = [[ +The command `\pgfkeysinstallkeyfilter{`⟨full key⟩`}{`⟨optional +arguments⟩`}` has the same effect as `\pgfkeys{`⟨full +key⟩`/.install key filter={`⟨optional arguments⟩`}}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysinstallkeyfilter" + }, + pgfkeysinstallkeyfilterhandler = { + arguments = {{meta = "full key"}, {meta = "optional arguments"}}, + details = [[ +The command `\pgfkeysinstallkeyfilterhandler{`⟨full key⟩`}{`⟨optional +arguments⟩`}` has the same effect as `\pgfkeys{`⟨full +key⟩`/.install key filter handler={`⟨optional arguments⟩`}}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysinstallkeyfilterhandler" + }, + pgfkeysisfamilyactive = { + arguments = {{meta = "family"}}, + details = [[ +Sets the TeX-boolean `\ifpgfkeysfiltercontinue` to whether ⟨family⟩ is +active or not. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysisfamilyactive" + }, + pgfkeyslet = { + arguments = {{meta = "full key"}, {meta = "macro"}}, + details = [[ +Performs a `\let` statement so the ⟨full key⟩ points to the contents of +⟨macro⟩. + + \def\helloworld{Hello, world!} + \pgfkeyslet{/my family/my key}{\helloworld} + \pgfkeysvalueof{/my family/my key} + +You should never let a key be equal to `\relax`. Such a key may or may +not be indistinguishable from an undefined key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeyslet" + }, + pgfkeyssavekeyfilterstateto = { + arguments = {{meta = "macro"}}, + details = [[ +Creates `{macro}` which contains commands to re-activate the current key +filter and key filter handler. It can be used to temporarily switch the +key filter. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeyssavekeyfilterstateto" + }, + pgfkeyssetevalue = { + arguments = {{meta = "full key"}, {meta = "token text"}}, + details = [[ +The `\edef` version of `\pgfkeyssetvalue`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeyssetevalue" + }, + pgfkeyssetfamily = { + arguments = {{meta = "full key"}, {meta = "family"}}, + details = [[ +The command `\pgfkeyssetfamily``{full key}``{family}` has the same +effect as `\pgfkeys{`⟨full key⟩`/.belongs to family=``{family}``}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeyssetfamily" + }, + pgfkeyssetvalue = { + arguments = {{meta = "full key"}, {meta = "token text"}}, + details = [[ +Stores the ⟨token text⟩ in the ⟨full key⟩. The ⟨full key⟩ may not be a +partial key, so no default-path-adding is done. The ⟨token text⟩ can be +arbitrary tokens and may even contain things like `# ` or unbalanced +TeX-ifs. + + \pgfkeyssetvalue{/my family/my key}{Hello, world!} + \pgfkeysvalueof{/my family/my key} + +The setting of a key is always local to the current TeX group. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeyssetvalue" + }, + pgfkeysvalueof = { + arguments = {{meta = "full key"}}, + details = [[ +Inserts the value stored in ⟨full key⟩ at the current position into the +text. + + \pgfkeyssetvalue{/my family/my key}{Hello, world!} + \pgfkeysvalueof{/my family/my key} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysvalueof" + }, + pgflibraryfpuifactive = { + arguments = {{meta = "true-code"}, {meta = "false-code"}}, + details = [[ +This command can be used to execute either ⟨true-code⟩ or ⟨false-code⟩, +depending on whether the FPU has been activated or not. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflibraryfpuifactive" + }, + pgflindenmayersystem = { + arguments = {{meta = "name"}, {meta = "axiom"}, {meta = "order"}}, + details = [[ +Runs the L-system called ⟨name⟩ using the input string ⟨axiom⟩ for +⟨order⟩ iterations. In general, prior to calling this command, the +transformation matrix should be set appropriately for shifting and +rotating, and a move-to to the (transformed) origin should be executed. +This origin will be where the L-system starts. In addition, the relevant +keys should be set appropriately. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \pgfset{lindenmayer system/.cd, angle=60, step=2pt} + \foreach \x/\y in {0cm/1cm, 1.5cm/1.5cm, 2.5cm/0.5cm, 1cm/0cm}{ + \pgftransformshift{\pgfqpoint{\x}{\y}} + \pgfpathmoveto{\pgfpointorigin} + \pgflindenmayersystem{Koch curve}{F++F++F}{2} + \pgfusepath{stroke} + } + \end{tikzpicture} + +Note that it is perfectly feasible for an L-system to define special +symbols which perform the move-to and use-path operations. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflindenmayersystem" + }, + pgflowlevel = { + arguments = {{meta = "transformation code"}}, + details = [[ +This command concatenates the canvas transformation matrix with the +coordinate transformation specified by ⟨transformation code⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{1pt} + \pgflowlevel{\pgftransformscale{5}} + \draw (0,0) -- (0.4,.2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflowlevel" + }, + pgflowlevelobj = { + arguments = {{meta = "transformation code"}, {meta = "code"}}, + details = [[ +This command creates a local `{pgfscope}`. Inside this scope, +`\pgflowlevel` is first called with the argument ⟨transformation code⟩, +then the ⟨code⟩ is inserted. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{1pt} + \pgflowlevelobj{\pgftransformscale{5}} {\draw (0,0) -- (0.4,.2);} + \pgflowlevelobj{\pgftransformxshift{-1cm}}{\draw (0,0) -- (0.4,.2);} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflowlevelobj" + }, + pgflowlevelsynccm = { + details = [[ +This command concatenates the canvas transformation matrix with the +current coordinate transformation matrix. Afterward, the coordinate +transformation matrix is reset. + +The effect of this command is to "synchronize" the coordinate +transformation matrix and the canvas transformation matrix. All +transformations that were previously applied by the coordinate +transformations matrix are now applied by the canvas transformation +matrix. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{1pt} + \pgftransformscale{5} + \draw (0,0) -- (0.4,.2); + \pgftransformxshift{0.2cm} + \pgflowlevelsynccm + \draw[red] (0,0) -- (0.4,.2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflowlevelsynccm" + }, + pgflsystemcurrentleftangle = { + details = [[ +The angle the L-system will turn when it turns left. The value stored in +this macro may be changed if `\pgflsystemrandomizeleftangle` is used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemcurrentleftangle" + }, + pgflsystemcurrentrightangle = { + details = [[ +The angle the L-system will turn when it turns right. The value stored +in this macro may be changed if `\pgflsystemrandomizerightangle` is +used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemcurrentrightangle" + }, + pgflsystemcurrentstep = { + details = [[ +The current "step" of the L-system (i.e., how far the system will move +forward if required). This is initially set to the value in the +TeX-dimensions `\pgflsystemstep`, but the actual value may be changed if +`\pgflsystemrandomizestep` is used (see below). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemcurrentstep" + }, + pgflsystemdrawforward = { + details = [[ +Move forward in the current direction, by `\pgflsystemcurrentstep`, +drawing a line in the process. This macro calls +`\pgflsystemrandomizestep`. Internally, PGF simply shifts the +transformation matrix in the positive direction of the current +(transformed) x-axis by `\pgflsystemstep` and then executes a line-to to +the (newly transformed) origin. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemdrawforward" + }, + pgflsystemmoveforward = { + details = [[ +Move forward in the current direction, by `\pgflsystemcurrentstep`, +without drawing a line. This macro calls `\pgflsystemrandomizestep`. PGF +executes a transformation as above, but executes a move-to to the (newly +transformed) origin. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemmoveforward" + }, + pgflsystemrandomizeleftangle = { + details = [[ +Randomizes the value in `\pgflsystemcurrentleftangle` according to the +value of the `randomize angle percent` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemrandomizeleftangle" + }, + pgflsystemrandomizerightangle = { + details = [[ +Randomizes the value in `\pgflsystemcurrentrightangle` according to the +value of the `randomize angle` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemrandomizerightangle" + }, + pgflsystemrandomizestep = { + details = [[ +Randomizes the value in `\pgflsystemcurrentstep` according to the +current value of the key `randomize step percent`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemrandomizestep" + }, + pgflsystemrestorestate = { + details = [[ +Restore the last saved position and orientation. Internally, PGF closes +a TeX-group, restoring the transformation matrix of the outer scope, and +a move-to command is executed to the (transformed) origin. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemrestorestate" + }, + pgflsystemsavestate = { + details = [[ +Save the current position and orientation. Internally, PGF simply starts +a new TeX-group. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemsavestate" + }, + pgflsystemturnleft = { + details = [[ +Turn left by `\pgflsystemcurrentleftangle`. Internally, PGF simply +rotates the transformation matrix. This macro calls +`\pgflsystemrandomizeleftangle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemturnleft" + }, + pgflsystemturnright = { + details = [[ +Turn right by `\pgflsystemcurrentrightangle`. Internally, PGF simply +rotates the transformation matrix. This macro calls +`\pgflsystemrandomizerightangle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemturnright" + }, + pgfmathaddtocount = { + arguments = {{meta = "count register"}, {meta = "expression"}}, + details = [[ +Adds the *truncated* value of ⟨expression⟩ to the TeX ⟨count register⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathaddtocount" + }, + pgfmathaddtocounter = { + arguments = {{meta = "counter"}, {meta = "expression"}}, + details = [[ +Adds the *truncated* value of ⟨expression⟩ to ⟨counter⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathaddtocounter" + }, + pgfmathaddtolength = { + arguments = {{meta = "register"}, {meta = "expression"}}, + details = [[ +Adds the value of ⟨expression⟩ to the TeX ⟨register⟩. All of the special +consideration mentioned for `\pgfmathsetlength` also apply here in the +same way. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathaddtolength" + }, + pgfmathanglebetweenlines = { + arguments = { + {meta = "$p_1$"}, + {meta = "$q_1$"}, + {meta = "$p_2$"}, + {meta = "$q_2$"} + }, + details = [[ +Returns the clockwise angle between a line going through $p_1$ and $q_1$ +and a line going through $p_2$ and $q_2$. + + \pgfmathanglebetweenlines{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}} + {\pgfpoint{0cm}{1cm}}{\pgfpoint{1cm}{0cm}} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathanglebetweenlines" + }, + pgfmathanglebetweenpoints = { + arguments = {{meta = "p"}, {meta = "q"}}, + details = [[ +Returns the angle of a line from ⟨p⟩ to ⟨q⟩ relative to a line going +straight right from ⟨p⟩. + + \pgfmathanglebetweenpoints{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathanglebetweenpoints" + }, + pgfmathapproxequalto = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +Defines `\pgfmathresult` 1.0 if $\rvert ⟨x⟩ - ⟨y⟩ \lvert < + 0.0001$, but 0.0 otherwise. As a side-effect, the global boolean +`\ifpgfmathcomparison` will be set accordingly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathapproxequalto" + }, + pgfmathbasetoBase = { + arguments = { + {meta = "macro"}, + {meta = "number"}, + {meta = "base-1"}, + {meta = "base-2"} + }, + details = [[ +Defines ⟨macro⟩ as the result of converting ⟨number⟩ from base ⟨base-1⟩ +to base ⟨base-2⟩. Alphabetic digits in ⟨number⟩ can be upper or lower +case, but any resulting alphabetic digits are in *upper case*. + + \pgfmathbasetoBase\mynumber{121212}{3}{12} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathbasetoBase" + }, + pgfmathbasetobase = { + arguments = { + {meta = "macro"}, + {meta = "number"}, + {meta = "base-1"}, + {meta = "base-2"} + }, + details = [[ +Defines ⟨macro⟩ as the result of converting ⟨number⟩ from base ⟨base-1⟩ +to base ⟨base-2⟩. Alphabetic digits in ⟨number⟩ can be upper or lower +case, but any resulting alphabetic digits are in *lower case*. + + \pgfmathbasetobase\mynumber{11011011}{2}{16} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathbasetobase" + }, + pgfmathbasetodec = { + arguments = {{meta = "macro"}, {meta = "number"}, {meta = "base"}}, + details = [[ +Defines ⟨macro⟩ as the result of converting ⟨number⟩ from base ⟨base⟩ to +base 10. Alphabetic digits can be upper or lower case. + + \pgfmathbasetodec\mynumber{107f}{16} \mynumber + +Note that, as usual in TeX, the braces around an argument can be omitted +if the argument is just a single token (a macro name is a single token). + + \pgfmathbasetodec\mynumber{33FC}{20} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathbasetodec" + }, + pgfmathdeclarefunction = { + arguments = { + {literal = "*"}, + {meta = "function name"}, + {meta = "number of arguments"}, + {meta = "code"} + }, + details = [[ +This will set up the parser to recognize a function called ⟨name⟩. The +name of the function can consist of, uppercase or lowercase letters, +numbers or the underscore `_ `. In line with many programming languages, +a function name cannot begin with a number or contain any spaces. The +function may not have been declared earlier, unless the optional star +(`*`) is provided, which forces an "overwriting" of the function by the +new function. Note that you *should never change the arity of standard +functions* and you should normally use `\pgfmathredeclarefunction`, +which does not allow you to do anything wrong here. + +The ⟨number of arguments⟩ can be any positive integer, zero, or the +value `...`, which indicates a variable number of arguments. PGF treats +constants, such as `pi` and `e`, as functions with zero arguments. +Functions with more than nine arguments or with a variable number of +arguments are a "bit special" and are discussed below. + +The effect of ⟨code⟩ should be to set the macro `\pgfmathresult` to the +correct value (namely to the result of the computation without units). +Furthermore, the function should have no other side effects, that is, it +should not change any global values. As an example, consider the +creation of a new function `double`, which takes one argument, and +returns the value of that argument times two. + + \makeatletter + \pgfmathdeclarefunction{double}{1}{ + \begingroup + \pgf@x=#1pt\relax + \multiply\pgf@x by2\relax + \pgfmathreturn\pgf@x + \endgroup + } + \makeatother + \pgfmathparse{double(44.3)}\pgfmathresult + +The macro `\pgfmathreturn`⟨tokens⟩ must be directly followed by an +`\endgroup` and will save the result of the computation, by defining +`\pgfmathresult` as the expansion of ⟨tokens⟩ (without units) outside +the group, so ⟨tokens⟩ must be something that can be assigned to a +dimension register. + +Alternatively, the `\pgfmathsmuggle`⟨macro⟩ can be used. This must also +be directly followed by an `\endgroup` and will simply "smuggle" the +definition of ⟨macro⟩ outside the TeX-group. + +By performing computations within a TeX-group, PGF registers such as +`\pgf@x`, `\pgf@y` and `\c@pgf@counta`, `\c@pgfcountb`, and so forth, +can be used at will. + +Beyond setting up the parser, this command also defines two macros which +provide access to the function independently of the parser: + +- `\pgfmath`⟨function name⟩ + + This macro will provide a "public" interface for the function + ⟨function name⟩ allowing the function to be called independently of + the parser. All arguments passed to this macro are evaluated using + `\pgfmathparse` and then passed on to the following macro: + +- `\pgfmath`⟨function name⟩`@` + + This macro is the "private" implementation of the function's + algorithm (but note that, for speed, the parser calls this macro + rather than the "public" one). Arguments passed to this macro are + expected to be numbers without units. It is defined using ⟨code⟩, + but need not be self-contained. + +For functions that are declared with less than ten arguments, the public +macro is defined in the same way as normal TeX macros using, for +example, `\def\pgfmathNoArgs{`⟨code⟩`}` for a function with no +arguments, or `\def\pgfmathThreeArgs# 1# 2# 3{`⟨code⟩`}` for a function +with three arguments. The private macro is defined in the same way, and +each argument can therefore be accessed in ⟨code⟩ using `# 1`, `# 2` and +so on. + +For functions with more than nine arguments, or functions with a +variable number of arguments, these macros are only defined as taking +*one* argument. The public macro expects its arguments to be comma +separated, for example, `\pgfmathVariableArgs{1.1,3.5,-1.5,2.6}`. Each +argument is parsed and passed on to the private macro as follows: +`\pgfmathVariableArgs@{{1.1}{3.5}{-1.5}{2.6}}`. This means that some +"extra work" will be required to access each argument (although it is a +fairly simple task). + +Note that there are two exceptions to this arrangement: the public +versions of the `min` and `max` functions still take two arguments for +compatibility with older versions, but each of these arguments can take +several comma separated values. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathdeclarefunction" + }, + pgfmathdeclarerandomlist = { + arguments = {{meta = "list name"}}, + details = [[ +This creates a list of items with the name ⟨list name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathdeclarerandomlist" + }, + pgfmathdectoBase = { + arguments = {{meta = "macro"}, {meta = "number"}, {meta = "base"}}, + details = [[ +Defines ⟨macro⟩ as the result of converting ⟨number⟩ from base 10 to +base ⟨base⟩. Any resulting alphabetic digits are in *upper case*. + + \pgfmathdectoBase\mynumber{65535}{16} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathdectoBase" + }, + pgfmathdectobase = { + arguments = {{meta = "macro"}, {meta = "number"}, {meta = "base"}}, + details = [[ +Defines ⟨macro⟩ as the result of converting ⟨number⟩ from base 10 to +base ⟨base⟩. Any resulting alphabetic digits are in *lower case*. + + \pgfmathdectobase\mynumber{65535}{16} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathdectobase" + }, + pgfmathfloat = { + arguments = {{meta = "op"}}, + details = [[ +Methods of this form constitute the replacement operations where ⟨op⟩ +can be any of the well-known math operations. + +Thus, `\pgfmathfloatadd` is the counterpart for `\pgfmathadd` and so on. +The semantics and number of arguments is the same, but all input and +output arguments are *expected* to be floating point numbers. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloat" + }, + pgfmathfloatabserror = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +Defines `\pgfmathresult` to be the absolute error between two floating +point numbers $x$ and $y$, $\lvert x - y\rvert$ and returns the result +as floating point number. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatabserror" + }, + pgfmathfloatcreate = { + arguments = {{meta = "flags"}, {meta = "mantissa"}, {meta = "exponent"}}, + details = [[ +Defines `\pgfmathresult` as the floating point number encoded by +⟨flags⟩, ⟨mantissa⟩ and ⟨exponent⟩. + +All arguments are characters and will be expanded using `\edef`. + + \pgfmathfloatcreate{1}{1.0}{327} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatcreate" + }, + pgfmathfloatgetexponent = { + arguments = {{meta = "x"}, {meta = "exponentcount"}}, + details = [[ +Extracts the exponent of ⟨x⟩ into the count register ⟨exponentcount⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatgetexponent" + }, + pgfmathfloatgetflags = { + arguments = {{meta = "x"}, {meta = "flagscount"}}, + details = [[ +Extracts the flags of ⟨x⟩ into the count register ⟨flagscount⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatgetflags" + }, + pgfmathfloatgetflagstomacro = { + arguments = {{meta = "x"}, {meta = "macro"}}, + details = [[ +Extracts the flags of ⟨x⟩ into the macro ⟨macro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatgetflagstomacro" + }, + pgfmathfloatgetmantissa = { + arguments = {{meta = "x"}, {meta = "mantissadimen"}}, + details = [[ +Extracts the mantissa of ⟨x⟩ into the dimen register ⟨mantissadimen⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatgetmantissa" + }, + pgfmathfloatgetmantissatok = { + arguments = {{meta = "x"}, {meta = "mantissatoks"}}, + details = [[ +Extracts the mantissa of ⟨x⟩ into the token register ⟨mantissatoks⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatgetmantissatok" + }, + pgfmathfloatifapproxequalrel = { + arguments = { + {meta = "a"}, + {meta = "b"}, + {meta = "true-code"}, + {meta = "false-code"} + }, + details = [[ +Computes the relative error between ⟨a⟩ and ⟨b⟩ (assuming ⟨b⟩$\neq 0$) +and invokes ⟨true-code⟩ if the relative error is below +`/pgf/fpu/rel thresh` and ⟨false-code⟩ if that is not the case. + +The input arguments will be parsed with `\pgfmathfloatparsenumber`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatifapproxequalrel" + }, + pgfmathfloatifflags = { + arguments = { + {meta = "floating point number"}, + {meta = "flag"}, + {meta = "true-code"}, + {meta = "false-code"} + }, + details = [[ +Invokes ⟨true-code⟩ if the flag of ⟨floating point number⟩ equals ⟨flag⟩ +and ⟨false-code⟩ otherwise. + +The argument ⟨flag⟩ can be one of + +0 +to test for zero, + +1 +to test for positive numbers, + +\+ +to test for positive numbers, + +2 +to test for negative numbers, + +\- +to test for negative numbers, + +3 +for "not-a-number", + +4 +for $+\infty$, + +5 +for $-\infty$. + + + + \pgfmathfloatparsenumber{42} + \pgfmathfloatifflags{\pgfmathresult}{0}{It's zero!}{It's not zero!} + \pgfmathfloatifflags{\pgfmathresult}{1}{It's positive!}{It's not positive!} + \pgfmathfloatifflags{\pgfmathresult}{2}{It's negative!}{It's not negative!} + + % or, equivalently + \pgfmathfloatifflags{\pgfmathresult}{+}{It's positive!}{It's not positive!} + \pgfmathfloatifflags{\pgfmathresult}{-}{It's negative!}{It's not negative!} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatifflags" + }, + pgfmathfloatint = { + arguments = {{meta = "x"}}, + details = [[ +Returns the integer part of the floating point number ⟨x⟩, by truncating +any digits after the period. This methods truncates the absolute value +$\rvert x \lvert$ to the next smaller integer and restores the original +sign afterwards. + +The result is returned as floating point number as well. + +See also `\pgfmathfloattoint` which returns the number in integer +format. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatint" + }, + pgfmathfloatlessthan = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +Defines `\pgfmathresult` as $1.0$ if $⟨x⟩ < ⟨y⟩$, but $0.0$ otherwise. +It also sets the global TeX-boolean `\pgfmathfloatcomparison` +accordingly. The arguments ⟨x⟩ and ⟨y⟩ are expected to be numbers which +have already been processed by `\pgfmathfloatparsenumber`. Arithmetic is +carried out using TeX-registers for exponent- and mantissa comparison. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatlessthan" + }, + pgfmathfloatmultiplyfixed = { + arguments = {{meta = "float"}, {meta = "fixed"}}, + details = [[ +Defines `\pgfmathresult` to be $⟨float⟩ \cdot ⟨fixed⟩$ where ⟨float⟩ is +a floating point number and ⟨fixed⟩ is a fixed point number. The +computation is performed in floating point arithmetics, that means we +compute $m \cdot ⟨fixed⟩$ and renormalize the result where $m$ is the +mantissa of ⟨float⟩. + +This operation renormalizes ⟨float⟩ with +`\pgfmathfloattoextentedprecision` before the operation, that means it +is intended for relatively small arguments of ⟨fixed⟩. The result is a +floating point number. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatmultiplyfixed" + }, + pgfmathfloatparsenumber = { + arguments = {{meta = "x"}}, + details = [[ +Reads a number of arbitrary magnitude and precision and stores its +result into `\pgfmathresult` as floating point number $m \cdot 10^e$ +with mantissa and exponent base $10$. + +The algorithm and the storage format is purely text-based. The number is +stored as a triple of flags, a positive mantissa and an exponent, such +as + + \pgfmathfloatparsenumber{2} + \pgfmathresult + +Please do not rely on the low-level representation here, use +`\pgfmathfloattomacro` (and its variants) and `\pgfmathfloatcreate` if +you want to work with these components. + +The flags encoded in `\pgfmathresult` are represented as a digit where +'$0$' stands for the number $\pm 0\cdot 10^0$, '$1$' stands for a +positive sign, '$2$' means a negative sign, '$3$' stands for 'not a +number', '$4$' means $+\infty$ and '$5$' stands for $-\infty$. + +The mantissa is a normalized real number $m \in \mathbb{R}$, $1 \le m < + 10$. It always contains a period and at least one digit after the +period. The exponent is an integer. + +Examples: + + \pgfmathfloatparsenumber{0} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + + \pgfmathfloatparsenumber{0.2} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + + \pgfmathfloatparsenumber{42} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + + \pgfmathfloatparsenumber{20.5E+2} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + + \pgfmathfloatparsenumber{1e6} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + + \pgfmathfloatparsenumber{5.21513e-11} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + +The argument ⟨x⟩ may be given in fixed point format or the scientific +"e" (or "E") notation. The scientific notation does not necessarily need +to be normalized. The supported exponent range is (currently) only +limited by the TeX-integer range (which uses 31 bit integer numbers). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatparsenumber" + }, + pgfmathfloatqparsenumber = { + arguments = {{meta = "x"}}, + details = [[ +The same as `\pgfmathfloatparsenumber`, but does not perform sanity +checking. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatqparsenumber" + }, + pgfmathfloatrelerror = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +Defines `\pgfmathresult` to be the relative error between two floating +point numbers $x$ and $y$, $\lvert x - y\rvert / \lvert y \rvert$ and +returns the result as floating point number. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatrelerror" + }, + pgfmathfloatround = { + arguments = {{meta = "x"}}, + details = [[ +Rounds a normalized floating point number to a prescribed precision and +writes the result to `\pgfmathresult`. + +The desired precision can be configured with +`/pgf/number format/precision`, see section ??. + +This method employs `\pgfmathroundto` to round the mantissa and applies +renormalization if necessary. + +As a side effect, the global boolean `\ifpgfmathfloatroundhasperiod` +will be set to true if and only if the resulting mantissa has a period. + + \pgfmathfloatparsenumber{52.5864} + \pgfmathfloatround{\pgfmathresult} + \pgfmathfloattosci{\pgfmathresult} + \pgfmathresult + + \pgfmathfloatparsenumber{9.995} + \pgfmathfloatround{\pgfmathresult} + \pgfmathfloattosci{\pgfmathresult} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatround" + }, + pgfmathfloatroundzerofill = { + arguments = {{meta = "x"}}, + details = [[ +A variant of `\pgfmathfloatround` produces always the same number of +digits after the period (it includes zeros if necessary). + + \pgfmathfloatparsenumber{52.5864} + \pgfmathfloatroundzerofill{\pgfmathresult} + \pgfmathfloattosci{\pgfmathresult} + \pgfmathresult + + \pgfmathfloatparsenumber{9.995} + \pgfmathfloatroundzerofill{\pgfmathresult} + \pgfmathfloattosci{\pgfmathresult} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatroundzerofill" + }, + pgfmathfloatsetextprecision = { + arguments = {{meta = "shift"}}, + details = [[ +Sets the precision used inside of `\pgfmathfloattoextentedprecision` to +⟨shift⟩. + +The different choices are + + --- ------------------ -------- ----------------- ------------------------------------------------- + 0 normalization to $0$ $\le m < 1$ (disable extended precision) + 1 normalization to $10$ $\le m < 100$ + 2 normalization to $100$ $\le m < 1000$ (default of `\pgfmathfloattoextentedprecision`) + 3 normalization to $1000$ $\le m < 10000$ + --- ------------------ -------- ----------------- ------------------------------------------------- +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatsetextprecision" + }, + pgfmathfloatshift = { + arguments = {{meta = "x"}, {meta = "num"}}, + details = [[ +Defines `\pgfmathresult` to be $⟨x⟩ \cdot 10^{⟨num⟩}$. The operation is +an arithmetic shift base ten and modifies only the exponent of ⟨x⟩. The +argument ⟨num⟩ is expected to be a (positive or negative) integer. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatshift" + }, + pgfmathfloattoextentedprecision = { + arguments = {{meta = "x"}}, + details = [[ +Renormalizes ⟨x⟩ to extended precision mantissa, meaning $100 \le m < + 1000$ instead of $1 \le m < 10$. + +The "extended precision" means we have higher accuracy when we apply +pgfmath operations to mantissas. + +The input argument is expected to be a normalized floating point number; +the output argument is a non-normalized floating point number (well, +normalized to extended precision). + +The operation is supposed to be very fast. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattoextentedprecision" + }, + pgfmathfloattofixed = { + arguments = {{meta = "x"}}, + details = [[ +Converts a number in floating point representation to a fixed point +number. It is a counterpart to `\pgfmathfloatparsenumber`. The algorithm +is purely text based and defines `\pgfmathresult` as a string sequence +which represents the floating point number ⟨x⟩ as a fixed point number +(of arbitrary precision). + + \pgfmathfloatparsenumber{0.00052} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E + $\to$ + \pgfmathfloattofixed{\pgfmathresult} + \pgfmathresult + + \pgfmathfloatparsenumber{123.456e4} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E + $\to$ + \pgfmathfloattofixed{\pgfmathresult} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattofixed" + }, + pgfmathfloattoint = { + arguments = {{meta = "x"}}, + details = [[ +Converts a number from low-level floating point representation to an +integer (by truncating the fractional part). + + \pgfmathfloatparsenumber{123456} + \pgfmathfloattoint{\pgfmathresult} + \pgfmathresult + +See also `\pgfmathfloatint` which returns the result as float. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattoint" + }, + pgfmathfloattomacro = { + arguments = { + {meta = "x"}, + {meta = "flagsmacro"}, + {meta = "mantissamacro"}, + {meta = "exponentmacro"} + }, + details = [[ +Extracts the flags of a floating point number ⟨x⟩ to ⟨flagsmacro⟩, the +mantissa to ⟨mantissamacro⟩ and the exponent to ⟨exponentmacro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattomacro" + }, + pgfmathfloattoregisters = { + arguments = { + {meta = "x"}, + {meta = "flagscount"}, + {meta = "mantissadimen"}, + {meta = "exponentcount"} + }, + details = [[ +Takes a floating point number ⟨x⟩ as input and writes flags to count +register ⟨flagscount⟩, mantissa to dimen register ⟨mantissadimen⟩ and +exponent to count register ⟨exponentcount⟩. + +Please note that this method rounds the mantissa to TeX-precision. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattoregisters" + }, + pgfmathfloattoregisterstok = { + arguments = { + {meta = "x"}, + {meta = "flagscount"}, + {meta = "mantissatoks"}, + {meta = "exponentcount"} + }, + details = [[ +A variant of `\pgfmathfloattoregisters` which writes the mantissa into a +token register. It maintains the full input precision. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattoregisterstok" + }, + pgfmathfloattosci = { + arguments = {{meta = "float"}}, + details = [[ +Converts a number from low-level floating point representation to +scientific format, $1.234e4$. The result will be assigned to the macro +`\pgfmathresult`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattosci" + }, + pgfmathfloatvalueof = { + arguments = {{meta = "float"}}, + details = [[ +Expands a number from low-level floating point representation to +scientific format, $1.234e4$. + +Use `\pgfmathfloatvalueof` in contexts where only expandable macros are +allowed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatvalueof" + }, + pgfmathgeneratepseudorandomnumber = { + details = [[ +Defines `\pgfmathresult` as a pseudo-random integer between 1 and +$2^{31}-1$. This uses a linear congruency generator, based on ideas of +Erich Janka. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathgeneratepseudorandomnumber" + }, + pgfmathifisint = { + arguments = { + {meta = "number constant"}, + {meta = "true code"}, + {meta = "false code"} + }, + details = [[ +A command which does the same check as `int detect`, but it invokes +⟨true code⟩ if the ⟨number constant⟩ actually is an integer and the +⟨false code⟩ if not. + +As a side-effect, `\pgfretval` will contain the parsed number, either in +integer format or as parsed floating point number. + +The argument ⟨number constant⟩ will be parsed with +`\pgfmathfloatparsenumber`. + + 15 \pgfmathifisint{15}{is an int: \pgfretval.}{is no int}\hspace{1em} + 15.5 \pgfmathifisint{15.5}{is an int: \pgfretval.}{is no int} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathifisint" + }, + pgfmathlog = { + arguments = {{meta = "x"}}, + details = [[ +Defines `\pgfmathresult` to be the natural logarithm of ⟨x⟩, $\ln(⟨x⟩)$. +This method is logically the same as `\pgfmathln`, but it applies +floating point arithmetics to read number ⟨x⟩ and employs the logarithm +identity $$\ln(m \cdot 10^e) = \ln(m) + e \cdot \ln(10)$$ to get the +result. The factor $\ln(10)$ is a constant, so only $\ln(m)$ with +$1 \le m < 10$ needs to be computed. This is done using standard pgf +math operations. + +Please note that ⟨x⟩ needs to be a number, expression parsing is not +possible here. + +If ⟨x⟩ is *not* a bounded positive real number (for example +$⟨x⟩ \le 0$), `\pgfmathresult` will be *empty*, no error message will be +generated. + + \pgfmathlog{1.452e-7} + \pgfmathresult + + \pgfmathlog{6.426e+8} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathlog" + }, + pgfmathparse = { + arguments = {{meta = "expression"}}, + details = [[ +This macro parses ⟨expression⟩ and returns the result without units in +the macro `\pgfmathresult`. + +`\pgfmathparse{2pt+3.5pt}` will set `\pgfmathresult` to the text `5.5`. + +In the following, the special properties of this command are explained. +The exact syntax of mathematical expressions is explained in Sections ?? +and ??. + +- The result stored in the macro `\pgfmathresult` is a decimal + *without units*. This is true regardless of whether the ⟨expression⟩ + contains any unit specification. All numbers with units are + converted to points first. See Section ?? for details on units. + +- The parser will recognize TeX registers and box dimensions, so + `\mydimen`, `0.5\mydimen`, `\wd\mybox`, `0.5\dp\mybox`, + `\mycount\mydimen` and so on can be parsed. + +- The $\varepsilon$-TeX extensions `\dimexpr`, `\numexpr`, + `\glueexpr`, and `\muexpr` are recognized and evaluated. The values + they result in will be used in the further evaluation, as if you had + put `\the` before them. + +- Parenthesis can be used to change the order of the evaluation. + +- Various functions are recognized, so it is possible to parse + `sin(.5*pi r)*60`, which means "the sine of $0.5$ times $\pi$ + radians, multiplied by 60". The argument of functions can be any + expression. + +- Scientific notation in the form `1.234e+4` is recognized (but the + restriction on the range of values still applies). The exponent + symbol can be upper or lower case (i.e., `E` or `e`). + +- An integer with a zero-prefix (excluding, of course zero itself), is + interpreted as an octal number and is automatically converted to + base 10. + +- An integer with prefix `0x` or `0X` is interpreted as a hexadecimal + number and is automatically converted to base 10. Alphabetic digits + can be in uppercase or lowercase. + +- An integer with prefix `0b` or `0B` is interpreted as a binary + number and is automatically converted to base 10. + +- An expression (or part of an expression) surrounded with double + quotes (i.e., the character `"`) will not be evaluated. Obviously + this should be used with great care. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathparse" + }, + pgfmathpostparse = { + details = [[ +At the end of the parse this command is executed, allowing some custom +action to be performed on the result of the parse. When this command is +executed, the macro `\pgfmathresult` will hold the result of the parse +(as always, without units). The result of the custom action should be +used to redefine `\pgfmathresult` appropriately. By default, this +command is equivalent to `\relax`. This differs from previous versions, +where, if the parsed expression contained no units, the result of the +parse was scaled according to the value in `\pgfmathresultunitscale` +(which by default was `1`). + +This scaling can be turned on again using: +`\let\pgfmathpostparse=\pgfmathscaleresult`. Note, however that by +scaling the result, the base conversion functions will not work, and the +`"` character should not be used to quote parts of an expression. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathpostparse" + }, + pgfmathprintnumber = { + arguments = {{meta = "x"}}, + details = [[ +Generates pretty-printed output for the (real) number ⟨x⟩. The input +number ⟨x⟩ is parsed using `\pgfmathfloatparsenumber` which allows +arbitrary precision. + +Numbers are typeset in math mode using the current set of number +printing options, see below. Optional arguments can also be provided +using `\pgfmathprintnumber[`⟨options⟩`]`⟨x⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathprintnumber" + }, + pgfmathprintnumberto = { + arguments = {{meta = "x"}, {meta = "macro"}}, + details = [[ +Returns the resulting number into ⟨macro⟩ instead of typesetting it +directly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathprintnumberto" + }, + pgfmathqparse = { + arguments = {{meta = "expression"}}, + details = [[ +This macro is similar to `\pgfmathparse`: it parses ⟨expression⟩ and +returns the result in the macro `\pgfmathresult`. It differs in two +respects. Firstly, `\pgfmathqparse` does not parse functions, scientific +notation, the prefixes for binary octal, or hexadecimal numbers, nor +does it accept the special use of `"`, `?` or `:` characters. Secondly, +numbers in ⟨expression⟩ *must* specify a TeX unit (except in such +instances as `0.5\pgf@x`), which greatly simplifies the problem of +parsing real numbers. As a result of these restrictions `\pgfmathqparse` +is about twice as fast as `\pgfmathparse`. Note that the result will +still be a number without units. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathqparse" + }, + pgfmathrandominteger = { + arguments = {{meta = "macro"}, {meta = "minimum"}, {meta = "maximum"}}, + details = [[ +This defines ⟨macro⟩ as a pseudo-randomly generated integer from the +range ⟨minimum⟩ to ⟨maximum⟩ (inclusive). + + \begin{pgfpicture} + \foreach \x in {1,...,50}{ + \pgfmathrandominteger{\a}{1}{50} + \pgfmathrandominteger{\b}{1}{50} + \pgfpathcircle{\pgfpoint{+\a pt}{+\b pt}}{+2pt} + \color{blue!40!white} + \pgfsetstrokecolor{blue!80!black} + \pgfusepath{stroke, fill} + } + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathrandominteger" + }, + pgfmathrandomitem = { + arguments = {{meta = "macro"}, {meta = "list name"}}, + details = [[ +Select an item from a random list ⟨list name⟩. The selected item is +placed in ⟨macro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathrandomitem" + }, + pgfmathreciprocal = { + arguments = {{meta = "x"}}, + details = [[ +Defines `\pgfmathresult` as $1\div⟨x⟩$. This provides greatest accuracy +when x is small. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathreciprocal" + }, + pgfmathredeclarefunction = { + arguments = {{meta = "function name"}, {meta = "code"}}, + details = [[ +This command redefines the `\pgfmath`⟨function name⟩`@` macro with the +new ⟨code⟩. See the description of the `\pgfmathdeclarefunction` for +details. You cannot change the number of arguments for an existing +function. + + \makeatletter + \pgfmathdeclarefunction{foo}{1}{ + \begingroup + \pgf@x=#1pt\relax + \multiply\pgf@x by2\relax + \pgfmathreturn\pgf@x + \endgroup + } + \pgfmathparse{foo(42)}\pgfmathresult + \pgfmathredeclarefunction{foo}{ + \begingroup + \pgf@x=#1pt\relax + \multiply\pgf@x by3\relax + \pgfmathreturn\pgf@x + \endgroup + } + \pgfmathparse{foo(42)}\pgfmathresult + \makeatother +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathredeclarefunction" + }, + pgfmathroundto = { + arguments = {{meta = "x"}}, + details = [[ +Rounds a fixed point number to prescribed precision and writes the +result to `\pgfmathresult`. + +The desired precision can be configured with +`/pgf/number format/precision`, see section ??. This section does also +contain application examples. + +Any trailing zeros after the period are discarded. The algorithm is +purely text based and allows to deal with precisions beyond TeX's fixed +point support. + +As a side effect, the global boolean `\ifpgfmathfloatroundhasperiod` +will be set to true if and only if the resulting mantissa has a period. +Furthermore, `\ifpgfmathfloatroundmayneedrenormalize` will be set to +true if and only if the rounding result's floating point representation +would have a larger exponent than ⟨x⟩. + + \pgfmathroundto{1} + \pgfmathresult + + \pgfmathroundto{4.685} + \pgfmathresult + + \pgfmathroundto{19999.9996} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathroundto" + }, + pgfmathroundtozerofill = { + arguments = {{meta = "x"}}, + details = [[ +A variant of `\pgfmathroundto` which always uses a fixed number of +digits behind the period. It fills missing digits with zeros. + + \pgfmathroundtozerofill{1} + \pgfmathresult + + \pgfmathroundto{4.685} + \pgfmathresult + + \pgfmathroundtozerofill{19999.9996} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathroundtozerofill" + }, + pgfmathsetbasenumberlength = { + arguments = {{meta = "integer"}}, + details = [[ +Sets the number of digits in the result of a base conversion to +⟨integer⟩. If the result of a conversion has less digits than this +number, it is prefixed with zeros. + + \pgfmathsetbasenumberlength{8} + \pgfmathdectobase\mynumber{15}{2} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetbasenumberlength" + }, + pgfmathsetcount = { + arguments = {{meta = "count register"}, {meta = "expression"}}, + details = [[ +Sets the value of the TeX ⟨count register⟩, to the *truncated* value +specified by ⟨expression⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetcount" + }, + pgfmathsetcounter = { + arguments = {{meta = "counter"}, {meta = "expression"}}, + details = [[ +Sets the value of the LaTeX ⟨counter⟩ to the *truncated* value specified +by ⟨expression⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetcounter" + }, + pgfmathsetlength = { + arguments = {{meta = "register"}, {meta = "expression"}}, + details = [[ +Basically, this command sets the length of the TeX ⟨register⟩ to the +value specified by ⟨expression⟩. However, there is some fine print: + +First, in case ⟨expression⟩ starts with a `+`, a simple TeX assignment +is done. In particular, ⟨register⟩ can be a glue register and +⟨expression⟩ be something like `+1pt plus 1fil` and the ⟨register⟩ will +be assigned the expected value. + +Second, when the ⟨expression⟩ does not start with `+`, it is first +parsed using `\pgfmathparse`, resulting in a (dimensionless) value +`\pgfmathresult`. Now, if the parser encountered the unit `mu` somewhere +in the expression, it assumes that ⟨register⟩ is a `\muskip` register +and will try to assign to ⟨register⟩ the value `\pgfmathresult` followed +by `mu`. Otherwise, in case `mu` was not encountered, it is assumed that +⟨register⟩ is a dimension register or a glue register and we assign +`\pgfmathresult` followed by `pt` to it. + +The net effect of the above is that you can write things like + + \muskipdef\mymuskip=0 + \pgfmathsetlength{\mymuskip}{1mu+3*4mu} \the\mymuskip + + \dimendef\mydimen=0 + \pgfmathsetlength{\mydimen}{1pt+3*4pt} \the\mydimen + + \skipdef\myskip=0 + \pgfmathsetlength{\myskip}{1pt+3*4pt} \the\myskip + +One thing that will *not* work is +`\pgfmathsetlength{\myskip}{1pt plus 1fil}` since the parser does not +support fill's. You can, however, use the `+` notation in this case: + + \skipdef\myskip=0 + \pgfmathsetlength{\myskip}{+1pt plus 1fil} \the\myskip +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetlength" + }, + pgfmathsetlengthmacro = { + arguments = {{meta = "macro"}, {meta = "expression"}}, + details = [[ +Defines ⟨macro⟩ as the value of ⟨expression⟩ LaTeX *in points*. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetlengthmacro" + }, + pgfmathsetmacro = { + arguments = {{meta = "macro"}, {meta = "expression"}}, + details = [[ +Defines ⟨macro⟩ as the value of ⟨expression⟩. The result is a decimal +without units. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetmacro" + }, + pgfmathsetseed = { + arguments = {{meta = "integer"}}, + details = [[ +Explicitly sets the seed for the pseudo-random number generator. By +default it is set to the value of `\time`$\times$`\year`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetseed" + }, + pgfmathtodigitlist = { + arguments = {{meta = "macro"}, {meta = "number"}}, + details = [[ +This command converts ⟨number⟩ into a comma-separated list of digits and +stores the result in ⟨macro⟩. The `{number}` is *not* parsed before +processing. + + \pgfmathsetbasenumberlength{8} + \begin{tikzpicture}[x=0.25cm, y=0.25cm] + \foreach \n [count=\y] in {0, 60, 102, 102, 126, 102, 102, 102, 0}{ + \pgfmathdectobase{\binary}{\n}{2} + \pgfmathtodigitlist{\digitlist}{\binary} + \foreach \digit [count=\x, evaluate={\c=\digit*50+15;}] in \digitlist + \fill [fill=black!\c] (\x, -\y) rectangle ++(1,1); + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathtodigitlist" + }, + pgfmathtruncatemacro = { + arguments = {{meta = "macro"}, {meta = "expression"}}, + details = [[ +Defines ⟨macro⟩ as the truncated value of ⟨expression⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathtruncatemacro" + }, + pgfmatrix = { + arguments = { + {meta = "shape"}, + {meta = "anchor"}, + {meta = "name"}, + {meta = "usage"}, + {meta = "shift"}, + {meta = "pre-code"}, + {meta = "matrix cells"} + }, + details = [[ +This command creates a node that contains a matrix. The name of the node +is ⟨name⟩, its shape is ⟨shape⟩ and the node is anchored at ⟨anchor⟩. + +The ⟨matrix cell⟩ parameter contains the cells of the matrix. In each +cell drawing commands may be given, which create a so-called cell +picture. For each cell picture a bounding box is computed and the cells +are aligned according to the rules outlined in the previous section. + +The resulting matrix is used as the `text` box of the node. As for a +normal node, the ⟨usage⟩ commands are applied, so that the path(s) of +the resulting node is (are) stroked or filled or whatever. + +**Specifying the cells and rows. ** Even though this command uses +`\halign` internally, there are two special rules for indicating cells: + +1. Cells in the same row must be separated using the macro + `\pgfmatrixnextcell` rather than `& `. Using `& ` will result in an + error message. + + However, you can make `& ` an active character and have it expand to + `\pgfmatrixnextcell`. This way, it will "look" as if `& ` is used. + +2. Rows are ended using the command `\pgfmatrixendrow`, but `\\` is set + up to mean the same by default. However, some environments like + `{minipage}` redefine `\\`, so it is good to have `\pgfmatrixendrow` + as a "fallback". + +3. Every row *including the last row* must be ended using the command + `\\` or `\pgfmatrixendrow`. + +Both `\pgfmatrixnextcell` and `\pgfmatrixendrow` (and, thus, also `\\`) +take an optional argument as explained in the Section ?? + + \begin{tikzpicture} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{} + { + \node {a}; \pgfmatrixnextcell \node {b}; \pgfmatrixendrow + \node {c}; \pgfmatrixnextcell \node {d}; \pgfmatrixendrow + } + \end{tikzpicture} + +**Anchoring matrices at nodes inside the matrix. ** The parameter +⟨shift⟩ is an additional negative shift for the node. Normally, such a +shift could be given beforehand (that is, the shift could be preapplied +to the current transformation matrix). However, when ⟨shift⟩ is +evaluated, you can refer to *temporary* positions of nodes inside the +matrix. In detail, the following happens: When the matrix has been +typeset, all nodes in the matrix temporarily get assigned their +positions in the matrix box. The origin of this coordinate system is at +the left baseline end of the matrix box, which corresponds to the `text` +anchor. The position ⟨shift⟩ is then interpreted inside this coordinate +system and then used for shifting. + +This allows you to use the parameter ⟨shift⟩ in the following way: If +you use `text` as the ⟨anchor⟩ and specify +`\pgfpointanchor{inner node}{some anchor}` for the parameter ⟨shift⟩, +where `inner node` is a node that is created in the matrix, then the +whole matrix will be shifted such that `inner node.some anchor` lies at +the origin of the whole picture. + +**Rotations and scaling. ** The matrix node is never rotated or scaled, +because the current coordinate transformation matrix is reset (except +for the translational part) at the beginning of `\pgfmatrix`. This is +intentional and will not change in the future. If you need to rotate or +scale the matrix, you must install an appropriate canvas transformation +yourself. + +However, nodes and stuff inside the cell pictures can be rotated and +scaled normally. + +**Callbacks. ** At the beginning and at the end of each cell the special +macros `\pgfmatrixbegincode`, `\pgfmatrixendcode` and possibly +`\pgfmatrixemptycode` are called. The effect is explained in Section ??. + +**Executing extra code. ** The parameter ⟨pre-code⟩ is executed at the +beginning of the outermost TeX-group enclosing the matrix node. It is +inside this TeX-group, but outside the matrix itself. It can be used for +different purposes: + +1. It can be used to simplify the next cell macro. For example, saying + `\let\& =\pgfmatrixnextcell` allows you to use `\& ` instead of + `\pgfmatrixnextcell`. You can also set the catcode of `& ` to + active. + +2. It can be used to issue an `\aftergroup` command. This allows you to + regain control after the `\pgfmatrix` command. (If you do not know + the `\aftergroup` command, you are probably blessed with a simple + and happy life.) + +**Special considerations concerning macro expansion. ** As said before, +the matrix is typeset using `\halign` internally. This command does a +lot of strange and magic things like expanding the first macro of every +cell in a most unusual manner. Here are some effects you may wish to be +aware of: + +- It is not necessary to actually mention `\pgfmatrixnextcell` or + `\pgfmatrixendrow` inside the ⟨matrix cells⟩. It suffices that the + macros inside ⟨matrix cells⟩ expand to these macros sooner or later. + +- In particular, you can define clever macros that insert columns and + rows as needed for special effects. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrix" + }, + pgfmatrixbegincode = { + details = [[ +This macro is executed at the beginning of non-empty cells. +Correspondingly, `\pgfmatrixendcode` is added at the end of every +non-empty cell. + + \begin{tikzpicture} + \def\pgfmatrixbegincode{\node[draw]\bgroup} + \def\pgfmatrixendcode{\egroup;} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell} + { + a \& b \& c \\ + d \& \& e \\ + } + \end{tikzpicture} + +Note that between `\pgfmatrixbegincode` and `\pgfmatrixendcode` there +will *not* only be the contents of the cell. Rather, PGF will add some +(invisible) commands for book-keeping purposes that involve `\let` and +`\gdef`. In particular, it is not a good idea to have +`\pgfmatrixbegincode` end with `\csname` and `\pgfmatrixendcode` start +with `\endcsname`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixbegincode" + }, + pgfmatrixcurrentcolumn = { + details = [[ +This counter stores the current column of the current cell of the +matrix. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixcurrentcolumn" + }, + pgfmatrixcurrentrow = { + details = [[ +This counter stores the current row of the current cell of the matrix. +Do not even think about changing this counter. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixcurrentrow" + }, + pgfmatrixemptycode = { + details = [[ +This macro is executed for empty cells. This means that PGF uses some +macro magic to determine whether a cell is empty (it immediately ends +with `\pgfmatrixemptycode` or `\pgfmatrixendrow`) and, if so, put this +macro inside the cell. + + \begin{tikzpicture} + \def\pgfmatrixemptycode{\node{empty};} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell} + { + \node {a}; \& \& \node {b}; \\ + \& \node{c}; \& \node {d}; \& \\ + } + \end{tikzpicture} + +As can be seen, the macro is not executed for empty cells at the end of +row when columns are added only later on. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixemptycode" + }, + pgfmatrixendcode = { + details = [[ +See the explanation above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixendcode" + }, + pgfmatrixendrow = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "additional sep list", + optional = true + } + }, + details = [[ +This command ends a line. The optional ⟨additional sep list⟩ is used to +determine the spacing between the row being ended and the next row. The +modes and the computation of $d$ is done in the same way as for columns. +For the last row the optional argument has no effect. + +Inside matrices (and only there) the command `\\` is set up to mean the +same as this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixendrow" + }, + pgfmatrixnextcell = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "additional sep list", + optional = true + } + }, + details = [[ +This command has two purposes: First, it is used to separate cells. +Second, by providing the optional argument ⟨additional sep list⟩ you can +modify the spacing between the columns that are separated by this +command. + +The optional ⟨additional sep list⟩ may only be provided when the +`\pgfmatrixnextcell` command starts a new column. Normally, this will +only be the case in the first row, but sometimes a later row has more +elements than the first row. In this case, the `\pgfmatrixnextcell` +commands that start the new columns in the later row may also have the +optional argument. Once a column has been started, subsequent uses of +this optional argument for the column have no effect. + +To determine the space between the two columns that are separated by +`\pgfmatrixnextcell`, the following algorithm is executed: + +1. Both the default separation list (as set up by + `\pgfsetmatrixcolumnsep`) and the ⟨additional sep list⟩ are + processed, in this order. If the ⟨additional sep list⟩ argument is + missing, only the default separation list is processed. + +2. Both lists may contain dimensions, separated by commas, as well as + occurrences of the keywords `between origins` and `between borders`. + +3. All dimensions occurring in either list are added together to arrive + at a dimension $d$. + +4. The last occurrence of either of the keywords is located. If neither + keyword is present, we proceed as if `between borders` were present. + +At the end of the algorithm, a dimension $d$ has been computed and one +of the two *modes* `between borders` and `between origins` has been +determined. Depending on which mode has been determined, the following +happens: + +- For the `between borders` mode, an additional horizontal space of + $d$ is added between the two columns. Note that $d$ may be negative. + +- For the `between origins` mode, the spacing between the two columns + is computed differently: Recall that the origins of the cell + pictures in both pictures lie on two vertical lines. The spacing + between the two columns is set up such that the horizontal distance + between these two lines is exactly $d$. + + This mode may only be used between columns *already introduced in + the first row*. + +All of the above rules boil down to the following effects: + +- A default spacing between columns should be set up using + `\pgfsetmatrixcolumnsep`. For example, you might say + `\pgfsetmatrixcolumnsep{5pt}` to have columns spaced apart by `5pt`. + You could say + + \pgfsetmatrixcolumnsep{1cm,between origins} + + to specify that horizontal space between the origins of cell + pictures in adjacent columns should be 1cm by default -- regardless + of the actual size of the cell pictures. + +- You can now use the optional argument of `\pgfmatrixnextcell` to + locally overrule the spacing between two columns. By saying + `\pgfmatrixnextcell[5pt]` you *add* 5pt to the space between of the + two columns, regardless of the mode. + + You can also (locally) change the spacing mode for these two + columns. For example, even if the normal spacing mode is + `between origins`, you can say + + \pgfmatrixnextcell[5pt,between borders] + + to locally change the mode for these columns to `between borders`. + + + + \begin{tikzpicture}[every node/.style=draw] + \pgfsetmatrixcolumnsep{1mm} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell} + { + \node {8}; \&[2mm] \node{1}; \&[-1mm] \node {6}; \\ + \node {3}; \& \node{5}; \& \node {7}; \\ + \node {4}; \& \node{9}; \& \node {2}; \\ + } + \end{tikzpicture} + + \begin{tikzpicture}[every node/.style=draw] + \pgfsetmatrixcolumnsep{1mm} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell} + { + \node {8}; \&[2mm] \node(a){1}; \&[1cm,between origins] \node(b){6}; \\ + \node {3}; \& \node {5}; \& \node {7}; \\ + \node {4}; \& \node {9}; \& \node {2}; \\ + } + \draw [<->,red,thick,every node/.style=] (a.center) -- (b.center) + node [above,midway] {11mm}; + \end{tikzpicture} + + \begin{tikzpicture}[every node/.style=draw] + \pgfsetmatrixcolumnsep{1cm,between origins} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell} + { + \node (a) {8}; \& \node (b) {1}; \&[between borders] \node (c) {6}; \\ + \node {3}; \& \node {5}; \& \node {7}; \\ + \node {4}; \& \node {9}; \& \node {2}; \\ + } + \begin{scope}[every node/.style=] + \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {10mm}; + \draw [<->,red,thick] (b.east) -- (c.west) node [above,midway] + {10mm}; + \end{scope} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixnextcell" + }, + pgfmetadecoratedcompleteddistance = { + details = [[ +The completed distance on the entire input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmetadecoratedcompleteddistance" + }, + pgfmetadecoratedinputsegmentcompleteddistance = { + details = [[ +The completed distance on the current input segment of the entire input +path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmetadecoratedinputsegmentcompleteddistance" + }, + pgfmetadecoratedinputsegmentremainingdistance = { + details = [[ +The remaining distance on the current input segment of the entire input +path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmetadecoratedinputsegmentremainingdistance" + }, + pgfmetadecoratedpathlength = { + details = [[ +The entire length of the entire input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmetadecoratedpathlength" + }, + pgfmetadecoratedremainingdistance = { + details = [[ +The remaining distance on the entire input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmetadecoratedremainingdistance" + }, + pgfmultipartnode = { + arguments = { + {meta = "shape"}, + {meta = "anchor"}, + {meta = "name"}, + {meta = "path usage command"} + }, + details = [[ +This command is the more general (and less user-friendly) version of the +`\pgfnode` command. While the `\pgfnode` command can only be used for +shapes that have a single part (which is the case for most shapes), this +command can also be used with multi-part nodes. + +When this command is called, for each node part of the node you must +have set up one TeX-box. Suppose the shape has two parts: The `text` +part and the `lower` part. Then, prior to calling `\pgfmultipartnode`, +you must have set up the boxes `\pgfnodeparttextbox` and +`\pgfnodepartlowerbox`. These boxes may contain any TeX-text. The shape +code will then compute the positions of the shape's anchors based on the +sizes of the these shapes. Finally, when the node is drawn, the boxes +are placed at the anchor positions `text` and `lower`. + + \setbox\pgfnodeparttextbox=\hbox{$q_1$} + \setbox\pgfnodepartlowerbox=\hbox{01} + \begin{pgfpicture} + \pgfmultipartnode{circle split}{center}{my state}{\pgfusepath{stroke}} + \end{pgfpicture} + +*Note:* Be careful when using the `\setbox` command inside a +`{pgfpicture}` command. You will have to use `\pgfinterruptpath` at the +beginning of the box and `\endpgfinterruptpath` at the end of the box to +make sure that the box is typeset correctly. In the above example this +problem was sidestepped by moving the box construction outside the +environment. + +*Note:* It is not necessary to use `\newbox` for every node part name. +Although you need a different box for each part of a single shape, two +different shapes may very well use the same box even when the names of +the parts are different. Suppose you have a `circle split` shape that +has a `lower` part and you have a `uml class` shape that has a `methods` +part. Then, in order to avoid exhausting TeX's limited number of box +registers, you can say + + \newbox\pgfnodepartlowerbox + \let\pgfnodepartmethodsbox=\pgfnodepartlowerbox + +Also, when you have a node part name with spaces like `class name`, it +may be useful to create an alias: + + \newbox\mybox + \expandafter\let\csname pgfnodepartclass namebox\endcsname=\mybox +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmultipartnode" + }, + pgfnode = { + arguments = { + {meta = "shape"}, + {meta = "anchor"}, + {meta = "label text"}, + {meta = "name"}, + {meta = "path usage command"} + }, + details = [[ +This command creates a new node. The ⟨shape⟩ of the node must have been +declared previously using `\pgfdeclareshape`. + +The shape is shifted such that the ⟨anchor⟩ is at the origin. In order +to place the shape somewhere else, use the coordinate transformation +prior to calling this command. + +The ⟨name⟩ is a name for later reference. If no name is given, nothing +will be "saved" for the node, it will just be drawn. + +The ⟨path usage command⟩ is executed for the background and the +foreground path (if the shape defines them). + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (4,3); + { + \pgftransformshift{\pgfpoint{1.5cm}{1cm}} + \pgfnode{rectangle}{north}{Hello World}{hellonode}{\pgfusepath{stroke}} + } + { + \color{red!20} + \pgftransformrotate{10} + \pgftransformshift{\pgfpoint{3cm}{1cm}} + \pgfnode{rectangle}{center} + {\color{black}Hello World}{hellonode}{\pgfusepath{fill}} + } + \end{tikzpicture} + +As can be seen, all coordinate transformations are also applied to the +text of the shape. Sometimes, it is desirable that the transformations +are applied to the point where the shape will be anchored, but you do +not wish the shape itself to be transformed. In this case, you should +call `\pgftransformresetnontranslations` prior to calling the `\pgfnode` +command. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (4,3); + { + \color{red!20} + \pgftransformrotate{10} + \pgftransformshift{\pgfpoint{3cm}{1cm}} + \pgftransformresetnontranslations + \pgfnode{rectangle}{center} + {\color{black}Hello World}{hellonode}{\pgfusepath{fill}} + } + \end{tikzpicture} + +The ⟨label text⟩ is typeset inside the TeX-box `\pgfnodeparttextbox`. +This box is shown at the `text` anchor of the node, if the node has a +`text` part. See the description of `\pgfmultipartnode` for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfnode" + }, + pgfnodealias = { + arguments = {{meta = "new name"}, {meta = "existing node"}}, + details = [[ +This command does not actually create a new node. Rather, it allows you +to subsequently access the node ⟨existing node⟩ using the name ⟨new +name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfnodealias" + }, + pgfnodepostsetupcode = { + arguments = {{meta = "node name"}, {meta = "code"}}, + details = [[ +When you call this macro inside a scope for which the +`\pgfpositionnodelater` has been called, the ⟨code⟩ will be stored +internally. Later, when the node named ⟨node name⟩ is actually +positioned using `\pgfpositionnodenow`, the ⟨code⟩ will be executed. +When this macro is called multiple times with the same ⟨node name⟩, the +⟨code⟩ accumulates. However, When `\pgfpositionnodenow` is called, the +code stored for the node is cleared. + +The main purpose of this mechanism is to allow TikZ to store so-called +"late options" with a node that will be positioned only later. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfnodepostsetupcode" + }, + pgfnoderename = { + arguments = {{meta = "new name"}, {meta = "existing node"}}, + details = [[ +This command renames an existing node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfnoderename" + }, + pgfooappend = { + arguments = {{meta = "attribute"}, {meta = "value"}}, + details = [[ +This method adds the given ⟨value⟩ to the ⟨attribute⟩ at the end. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooappend" + }, + pgfooclass = { + arguments = { + {delimiters = {"(", ")"}, meta = "list of superclasses"}, + {meta = "class name"}, + {meta = "body"} + }, + details = [[ +This command defines a class named ⟨class name⟩. The name of the class +can contain spaces and most other characters, but no periods. So, valid +class names are `MyClass` or `my class` or `Class_ C++_ emulation??1`. +The ⟨list of superclasses⟩ is optional just like the parenthesis around +it. + +The ⟨body⟩ is actually just executed, so any normal TeX-code is +permissible here. However, while the ⟨body⟩ is being executed, the +macros `\method` and `\attribute` are set up so that they can be used to +define methods and attributes for this class (the original meanings are +restored afterward). + +The definition of a class is local to the scope where the class has been +defined. + + \pgfooclass{stamp}{ + % This is the class stamp + + \attribute text; + \attribute rotation angle=20; + + \method stamp(#1) { % The constructor + ... + } + + \method apply(#1,#2) { % Causes the stamp to be shown at coordinate (#1,#2) + ... + } + } + + % We can now create objects of type "stamp" + +Concerning the list of base classes, the Method Resolution Order (MRO) +is computed using the C3 algorithm also used in Python, v2.3 and higher. +The linearization computed by the algorithm respects both local +precedence ordering and monotonicity. Resolution of both methods and +attributes depends on the MRO: when a method method name is called on an +object of class $C$, the system invokes method method name from the +first class in the MRO of $C$ which defines method method name; when an +object is created, each attribute `attr` is initialized to the value +specified in the first class in the MRO of $C$ which declares attribute +`attr`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooclass" + }, + pgfooeset = { + arguments = {{meta = "attribute"}, {meta = "value"}}, + details = [[ +Performs the same action as `\pgfooset` but in an `\edef` full expansion +context. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooeset" + }, + pgfoogc = { + details = [[ +This command causes the "garbage collector" to be invoked. The job of +this garbage collector is to free the global TeX-macros that are used by +"dead" objects (objects whose life-time has ended). This macro is called +automatically after every scope in which an object has been created, so +you normally do not need to call this macro yourself. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoogc" + }, + pgfooget = { + arguments = {{meta = "attribute"}, {meta = "macro"}}, + details = [[ +Reads the current value of ⟨attribute⟩ and stores the result in ⟨macro⟩. + + ... + \method get rotation (#1) { + \pgfooget{rotation angle}{#1} + } + ... + + \mystamp.get rotation(\therotation) + ``\therotation'' is now ``20'' (or whatever). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooget" + }, + pgfoolet = { + arguments = {{meta = "attribute"}, {meta = "macro"}}, + details = [[ +Sets the ⟨attribute⟩ of the current value to the current value of +⟨macro⟩ using TeX's `\let` command. + + \method foo () { + \pgfoolet{my func}\myfunc + % Changing \myfunc now has no effect on the value of attribute my func + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoolet" + }, + pgfoonew = { + arguments = { + {meta = "object handle or attribute"}, + {literal = "="}, + {literal = "new "}, + {meta = "class name"}, + {delimiters = {"(", ")"}, meta = "constructor arguments"} + }, + details = [[ +Causes a new object to be created. The class of the object will be +⟨class name⟩, which must previously have been declared using +`\pgfooclass`. Once the object has been created, the constructor method +of the object will be called with the parameter list set to ⟨constructor +arguments⟩. + +The resulting object is stored internally and its lifetime will end +exactly at the end of the current scope. + +Here is an example in which three stamp objects are created. + + \pgfoonew \firststamp=new stamp() + \pgfoonew \secondstamp=new stamp() + { + \pgfoonew \thirdstamp=new stamp() + ... + } + % \thirdstamp no longer exists, but \firststamp and \secondstamp do + % even if you try to store \thirdstamp in a global variable, trying + % to access it will result in an error. + +The optional ⟨object handle or attribute⟩ can either be an ⟨object +handle⟩ or an ⟨attribute⟩. When an ⟨object handle⟩ is given, it must be +a normal TeX macro name that will "point" to the object (handles are +discussed in more detail in Section ??). You can use this macro to call +methods of the object as discussed in the following section. When an +⟨attribute⟩ is given, it must be given in curly braces (the curly braces +are used to detect the presence of an attribute). In this case, a handle +to the newly created object is stored in this attribute. + + \pgfooclass{foo} + { + \attribute stamp obj; + \attribute another object; + + \method foo() { + \pgfoonew{stamp obj}=new stamp() + \pgfoonew{another object}=new bar() + } + ... + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoonew" + }, + pgfooobj = { + arguments = {{meta = "id"}}, + details = [[ +Provided that ⟨id⟩ is the id of an existing object (an object whose +life-time has not expired), calling this command yields a handle to this +object. The handle can then be used to call methods: + + % Create a new object: + \pgfoonew \mystamp=new stamp() + + % Get the object's id and store it in \myid: + \mystamp.get id(\myid) + + % The following two calls have the same effect: + \mystamp.apply(1,1) + \pgfooobj{\myid}.apply(1,1) +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooobj" + }, + pgfooprefix = { + arguments = {{meta = "attribute"}, {meta = "value"}}, + details = [[ +This method adds the given ⟨value⟩ to the ⟨attribute⟩ at the beginning. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooprefix" + }, + pgfooset = { + arguments = {{meta = "attribute"}, {meta = "value"}}, + details = [[ +Sets the ⟨attribute⟩ of the current object to ⟨value⟩. + + \method set rotation (#1) { + \pgfooset{rotation angle}{#1} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooset" + }, + pgfoosuper = { + arguments = {{literal = "("}, {meta = "class"}}, + details = [[ +This macro gives you finer control over which method gets invoked in +case of multiple inheritance. This macro calls ⟨method name⟩ of the +object specified by ⟨object handle⟩, but which implementation of the +method is called is determined as follows: it will be the implementation +in the first class (in the method resolution order) after ⟨class⟩ that +defines ⟨method name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoosuper" + }, + pgfoothis = { + details = [[ +This object handle is well-defined only when a method is being executed. +There, it is then set to point to the object for which the method is +being called, which allows you to call another method for the same +object. + + \pgfooclass{stamp}{ + % This is the class stamp + + \method stamp() {} + + \method apply(#1,#2) { + \pgfoothis.shift origin(#1,#2) + + % Draw the stamp: + \node [rotate=20,font=\huge] {Passed}; + } + + % Private method: + \method shift origin(#1,#2) { + \tikzset{xshift=#1,yshift=#2} + } + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoothis" + }, + pgfoovalueof = { + arguments = {{meta = "attribute"}}, + details = [[ +Expands (eventually) to the current value of ⟨attribute⟩ of the current +object. + + \method apply(#1,#2) { + \pgfoothis.shift origin(#1,#2) + + \node [rotate=\pgfoovalueof{rotation angle},font=\huge] + {\pgfoovalueof{text}}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoovalueof" + }, + pgfpagescurrentpagewillbelogicalpage = { + arguments = {{meta = "number"}}, + details = [[ +When the current TeX page has been typeset, it will be become the given +logical page ⟨number⟩. This command "interrupts" the normal order of +logical pages, that is, it behaves like the previous command and does +not update the ⟨current logical page⟩ counter. + + \pgfpagesuselayout{two screens with optional second} + ... + Text for main page. + \clearpage + + \pgfpagescurrentpagewillbelogicalpage{2} + Text that goes to second page + \clearpage + + Text for main page. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpagescurrentpagewillbelogicalpage" + }, + pgfpagesdeclarelayout = { + arguments = { + {meta = "layout"}, + {meta = "before actions"}, + {meta = "after actions"} + }, + details = [[ +This command predefines a ⟨layout⟩ that can later be installed using the +`\pgfpagesuselayout` command. + +When `\pgfpagesuselayout``{layout}``[options]` is called, the following +happens: First, the ⟨before actions⟩ are executed. They can be used, for +example, to set up default values for keys. Next, +`\setkeys{pgfpagesuselayoutoption}``{options}` is executed. Finally, the +⟨after actions⟩ are executed. + +Here is an example: + + \pgfpagesdeclarelayout{resize to} + { + \def\pgfpageoptionborder{0pt} + } + { + \pgfpagesphysicalpageoptions + {% + logical pages=1,% + physical height=\pgfpageoptionheight,% + physical width=\pgfpageoptionwidth% + } + \pgfpageslogicalpageoptions{1} + {% + resized width=\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% + border shrink=\pgfpageoptionborder,% + center=\pgfpoint{.5\pgfphysicalwidth}{.5\pgfphysicalheight}% + }% + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpagesdeclarelayout" + }, + pgfpageslogicalpageoptions = { + arguments = { + {meta = "logical page number"}, + {keys = "$ref:pgf#/keys/pgf", meta = "options"} + }, + details = [[ +This command is used to specify where the logical page number ⟨logical +page number⟩ will be placed on the physical page. In addition, this +command can be used to install additional "code" to be executed when +this page is put on the physical page. + +The number ⟨logical page number⟩ should be between 1 and ⟨logical +pages⟩, which has previously been installed using the +`\pgfpagesphysicalpageoptions` command. + +The following ⟨options⟩ may be given: + +- `center=`⟨pgf point⟩ specifies the center of the logical page inside + the physical page as a PGF-point. The origin of the coordinate + system of the physical page is at the *lower* left corner. + + \pgfpageslogicalpageoptions{1} + {% center logical page on middle of left side + center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}% + resized width=.5\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% + } + +- `resized width=`⟨size⟩ specifies the width that the logical page + should have *at most* on the physical page. To achieve this width, + the pages is scaled down appropriately *or more*. The "or more" part + can happen if the `resize height` option is also used. In this case, + the scaling is chosen such that both the specified height and width + are met. The aspect ratio of a logical page is not modified. + +- `resized height=`⟨height⟩ specifies the maximum height of the + logical page. + +- `original width=`⟨width⟩ specifies the width the TeX "thinks" that + the logical page has. This width is `\paperwidth` at the point of + invocation, by default. Note that setting this width to something + different from `\paperwidth` does *not* change the `\pagewidth` + during TeX's typesetting. You have to do that yourself. + + You need this option only for special logical pages that have a + height or width different from the normal one and for which you will + (later on) set these sizes yourself. + +- `original height=`⟨height⟩ works like `original width`. + +- `scale=`⟨factor⟩ scales the page by at least the given ⟨factor⟩. A + ⟨factor⟩ of `0.5` will half the size of the page, a factor or `2` + will double the size. "At least" means that if options like + `resize height` are given and if the scaling required to meet that + option is less than ⟨factor⟩, that other scaling is used instead. + +- `xscale=`⟨factor⟩ scales the logical page along the $x$-axis by the + given ⟨factor⟩. This scaling is done independently of any other + scaling. Mostly, this option is useful for a factor of `-1`, which + flips the page along the $y$-axis. The aspect ratio is not kept. + +- `yscale=`⟨factor⟩ works like `xscale`, only for the $y$-axis. + +- `rotation=`⟨degree⟩ rotates the page by ⟨degree⟩ around its center. + Use a degree of `90` or `-90` to go from portrait to landscape and + back. The rotation need not be a multiple of `90`. + +- `copy from=`⟨logical page number⟩. Normally, after a physical + shipout has occurred, all logical pages are voided in a loop. + However, if this option is given, the current logical page is filled + with the contents of the old logical page number ⟨logical page + number⟩. + + Have logical page 2 retain its contents: + + \pgfpageslogicalpageoptions{2}{copy from=2} + + Let logical page 2 show what logical page 1 showed on the + just-shipped-out physical page: + + \pgfpageslogicalpageoptions{2}{copy from=1} + +- `border shrink`=⟨size⟩ specifies an additional reduction of the size + to which the page is page is scaled. + +- `border code`=⟨code⟩. When this option is given, the ⟨code⟩ is + executed before the page box is inserted with a path preinstalled + that is a rectangle around the current logical page. Thus, setting + ⟨code⟩ to `\pgfstroke` draws a rectangle around the logical page. + Setting ⟨code⟩ to `\pgfsetlinewidth{3pt}\pgfstroke` results in a + thick (ugly) frame. Adding dashes and filling can result in + arbitrarily funky and distracting borders. + + You can also call `\pgfdiscardpath` and add your own path + construction code (for example to paint a rectangle with rounded + corners). The coordinate system is set up in such a way that a + rectangle starting at the origin and having the height and width of + TeX-box 0 will result in a rectangle filling exactly the logical + page currently being put on the physical page. The logical page is + inserted *after* these commands have been executed. + + Add a rectangle around the page: + + \pgfpageslogicalpageoptions{1}{border code=\pgfstroke} + +- `corner width`=⟨size⟩ adds black "rounded corners" to the page. See + the description of the predefined layout `rounded corners` on + page ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpageslogicalpageoptions" + }, + pgfpagesphysicalpageoptions = { + arguments = {{keys = "$ref:pgf#/keys/pgf", meta = "options"}}, + details = [[ +This command sets the characteristics of the "physical" page. For +example, it is used to specify how many logical pages there are and how +many logical pages must be accumulated before a physical page is shipped +out. How each individual logical page is typeset is specified using the +command `\pgfpageslogicalpageoptions`, described later. + +A layout for putting two portrait pages on a single landscape page: + + \pgfpagesphysicalpageoptions + {% + logical pages=2,% + physical height=\paperwidth,% + physical width=\paperheight,% + } + + \pgfpageslogicalpageoptions{1} + {% + resized width=.5\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% + center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}% + }% + \pgfpageslogicalpageoptions{2} + {% + resized width=.5\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% + center=\pgfpoint{.75\pgfphysicalwidth}{.5\pgfphysicalheight}% + }% + +The following ⟨options⟩ may be set: + +- `logical pages=`⟨logical pages⟩ specified how many logical pages + there are, in total. These are numbered 1 to ⟨logical pages⟩. + +- `first logical shipout=`⟨first⟩. See the next option. By default, + ⟨first⟩ is 1. + +- `last logical shipout=`⟨last⟩. Together with the previous option, + these two options define an interval of pages inside the range 1 to + ⟨logical pages⟩. Only this range is used to store the pages that are + shipped out by TeX. This means that after a physical shipout has + just occurred (or at the beginning), the first time TeX wishes to + perform a shipout, the page to be shipped out is stored in logical + page ⟨first⟩. The next time TeX performs a shipout, the page is + stored in logical page $⟨first⟩ +1$ and so on, until the logical + page ⟨last⟩ is also filled. Once this happens, a physical shipout + occurs and the process starts once more. + + Note that logical pages that lie outside the interval between + ⟨first⟩ and ⟨last⟩ are filled only indirectly or when special + commands are used. + + By default, ⟨last⟩ equals ⟨logical pages⟩. + +- `current logical shipout=`⟨current⟩ changes an internal counter such + that TeX's next logical shipout will be stored in logical page + ⟨current⟩. + + This option can be used to "warp" the logical page filling mechanism + to a certain page. You can both skip logical pages and overwrite + already filled logical pages. After the logical page ⟨current⟩ has + been filled, the internal counter is incremented normally as if the + logical page ⟨current⟩ had been "reached" normally. If you specify a + ⟨current⟩ larger than ⟨last⟩, a physical shipout will occur after + the logical page ⟨current⟩ has been filled. + +- `physical height=`⟨height⟩ specifies the height of the physical + pages. This height is typically different from the normal + `\paperheight`, which is used by TeX for its typesetting and page + breaking purposes. + +- `physical width=`⟨width⟩ specifies the physical width. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpagesphysicalpageoptions" + }, + pgfpagesshipoutlogicalpage = { + arguments = {{meta = "number"}, {meta = "box"}}, + details = [[ +This command sets to logical page ⟨number⟩ to ⟨box⟩. The ⟨box⟩ should be +the code of a TeX box command. This command does not influence the +counter ⟨current logical page⟩ and does not cause a physical shipout. + + \pgfpagesshipoutlogicalpage{0}\vbox{Hi!} + +This command can be used to set the contents of logical pages that are +normally not filled. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpagesshipoutlogicalpage" + }, + pgfpagesuselayout = { + arguments = { + {meta = "layout"}, + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + } + }, + details = [[ +Installs the specified ⟨layout⟩ with the given ⟨options⟩. The predefined +layouts and their permissible options are explained below. + +If this function is called multiple times, only the last call "wins". +You can thereby overwrite any previous settings. In particular, layouts +*do not* accumulate. + +`\pgfpagesuselayout{resize to}[a4paper]` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpagesuselayout" + }, + pgfparserdeffinal = { + arguments = {{meta = "parser name"}, {meta = "action"}}, + details = [[ +Every parser can call a final ⟨action⟩ after the state was switched to +`final`. This ⟨action⟩ is executed after everything else, so you can use +something that grabs more arguments if you want to. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserdeffinal" + }, + pgfparserdefunknown = { + arguments = {{meta = "parser name"}, {meta = "state"}, {meta = "action"}}, + details = [[ +With this macro you can define an ⟨action⟩ for the ⟨parser name⟩ parser +in ⟨state⟩ if no action was defined for the letter which was +encountered. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserdefunknown" + }, + pgfparserifmark = { + arguments = {{meta = "arg"}, {meta = "true"}, {meta = "false"}}, + details = [[ +Remember that some of the optional argument types set special marks? +With `\pgfparserifmark` you can test whether ⟨arg⟩ is such a mark. So if +there was no optional argument for the argument types `o` and `d` the +⟨true⟩ branch will be executed, else the ⟨false⟩ branch. For the `t` +type argument the ⟨true⟩ branch is executed if the token was +encountered. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserifmark" + }, + pgfparserletter = { + details = [[ +This macro stores the letter to which `\pgfparsertoken` was let. So if +you'd use `\pgfparserparse{foo}a` this macro would be defined with +`\def\pgfparserletter{a}`. This definition is done before any action +code is executed. There are four special cases: If the next token is of +category code 1, 2, 6, or 10, so with standard category codes the tokens +`{`, `}`, `# `, and (a space), it would be treated differently. In +those cases this macro expands to `\bgroup`, `\egroup`, `# # `, and for +the categories 1, 2, 6, and 10, respectively. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserletter" + }, + pgfparserparse = { + arguments = {{meta = "parser name"}, {meta = "text"}}, + details = [[ +This command is used to parse the ⟨text⟩ using the (previously defined) +parser named ⟨parser name⟩. + +The ⟨text⟩ is not contained in curly braces, rather it is all the text +that follows. The end of the text is determined implicitly, namely when +the final state of the parser has been reached. If you defined a final +action for the parser using `\pgfparserdeffinal` it is executed now. + +The parser works as follows: At any moment, it is in a certain *state*, +initially this state is called `initial`. Then, the first letter of the +⟨text⟩ is examined (using the `\futurelet` command). For each possible +state and each possible letter, some action code is stored in the parser +in a table. This code is then executed. This code may, but need not, +trigger a *state switch*, causing a new state to be set. The parser then +moves on to the next character of the text and repeats the whole +procedure, unless it is in the state `final`, which causes the parsing +process to stop immediately. + +In the following example, the parser counts the number of `a`'s in the +text, ignoring any `b`'s. The ⟨text⟩ ends with the first `c`. + + \newcount\mycount + \pgfparserdef{myparser}{initial}{the letter a}% + {\advance\mycount by 1\relax}% + \pgfparserdef{myparser}{initial}{the letter b}% + {} % do nothing + \pgfparserdef{myparser}{initial}{the letter c}% + {\pgfparserswitch{final}}% done! + + \pgfparserparse{myparser}aabaabababbbbbabaabcccc + There are \the\mycount\ a's. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserparse" + }, + pgfparserreinsert = { + details = [[ +You can use this as the final macro in an action of `\pgfparserdef` or +`\pgfparserdefunknown`. This has the effect that the contents of +`\pgfparserletter` will be parsed next. Without any redefinition the +result will be that the last token will be parsed again. You can change +the definition of `\pgfparserletter` just before `\pgfparserreinsert` as +well to parse some specific tokens next. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserreinsert" + }, + pgfparserset = { + arguments = {{meta = "key list"}}, + details = [[ +The `pgfparser` module has a few keys you can access through this macro. +It is just a shortcut for `\pgfset{/pgfparser/.cd,# 1}`. The available +keys are listed in subsection ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserset" + }, + pgfparserstate = { + details = [[ +Expands to the current state of the parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserstate" + }, + pgfparserswitch = { + arguments = {{meta = "state"}}, + details = [[ +This command can be called inside the action code of a parser to cause a +state switch to ⟨state⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserswitch" + }, + pgfparsertoken = { + details = [[ +This is the macro which is let to the following token with `\futurelet`. +You can use it inside an action code. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparsertoken" + }, + pgfparsetime = { + arguments = {{meta = "time"}}, + details = [[ +This command works like `\pgfmathparse` (indeed, it calls is +internally), but returns the result in the macro `\pgftimeresult` rather +than `\pgfmathresult`. Furthermore, the following changes are installed: + +- The postfix operator `s` is added, which has no effect. + +- The postfix operator `ms` is added, which divides a number by 1000, + so `2ms` equals 0.002s. + +- The postfix operator `min` is added, which multiplies a number + by 60. + +- The postfix operator `h` is added, which multiplies a number + by 3600. + +- The infix operator `:` is redefined, so that it multiplies its first + argument by 60 and adds the second. This implies that `1:20` equals + 80s and `01:00:00` equals 3600s. + +- The parsing of octal numbers is switched off to allow things like + `01:08` for 68s. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparsetime" + }, + pgfpatharc = { + arguments = { + {meta = "start angle"}, + {meta = "end angle"}, + {literal = "{"}, + {meta = "radius"}, + {literal = " and "}, + {meta = "y-radius"}, + {literal = "}"} + }, + details = [[ +This command appends a part of a circle (or an ellipse) to the current +path. Imagine the curve between ⟨start angle⟩ and ⟨end angle⟩ on a +circle of radius ⟨radius⟩ (if $⟨start angle⟩ < ⟨end + angle⟩$, the curve goes around the circle counterclockwise, +otherwise clockwise). This curve is now moved such that the point where +the curve starts is the previous last point of the path. Note that this +command will *not* start a new part of the path, which is important for +example for filling purposes. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{0cm}{1cm}} + \pgfpatharc{180}{90}{.5cm} + \pgfpathlineto{\pgfpoint{3cm}{1.5cm}} + \pgfpatharc{90}{-45}{.5cm} + \pgfusepath{fill} + \end{tikzpicture} + +Saying `\pgfpatharc{0}{360}{1cm}` "nearly" gives you a full circle. The +"nearly" refers to the fact that the circle will not be closed. You can +close it using `\pgfpathclose`. + +If the optional ⟨y-radius⟩ is given, the ⟨radius⟩ is the $x$-radius and +the ⟨y-radius⟩ the $y$-radius of the ellipse from which the curve is +taken: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharc{180}{45}{2cm and 1cm} + \pgfusepath{draw} + \end{tikzpicture} + +The axes of the circle or ellipse from which the arc is "taken" always +point up and right. However, the current coordinate transformation +matrix will have an effect on the arc. This can be used to, say, rotate +an arc: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformrotate{30} + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharc{180}{45}{2cm and 1cm} + \pgfusepath{draw} + \end{tikzpicture} + +The command will update the bounding box of the current path and +picture, if necessary. Unless rotation or shearing transformations are +applied, the bounding box will be tight. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpatharc" + }, + pgfpatharcaxes = { + arguments = { + {meta = "start angle"}, + {meta = "end angle"}, + {meta = "first axis"}, + {meta = "second axis"} + }, + details = [[ +This command is similar to `\pgfpatharc`. The main difference is how the +ellipse or circle is specified from which the arc is taken. The two +parameters ⟨first axis⟩ and ⟨second axis⟩ are the $0^\circ$-axis and the +$90^\circ$-axis of the ellipse from which the path is taken. Thus, +`\pgfpatharc{0}{90}{1cm and 2cm}` has the same effect as + + \pgfpatharcaxes{0}{90}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{2cm}} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2cm,5mm) (0,0) -- (0cm,1cm); + + \pgfpathmoveto{\pgfpoint{2cm}{5mm}} + \pgfpatharcaxes{0}{90}{\pgfpoint{2cm}{5mm}}{\pgfpoint{0cm}{1cm}} + \pgfusepath{draw} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpatharcaxes" + }, + pgfpatharcto = { + arguments = { + {meta = "x-radius"}, + {meta = "y-radius"}, + {meta = "rotation"}, + {meta = "large arc flag"}, + {meta = "counterclockwise flag"}, + {meta = "target point"} + }, + details = [[ +This command (which directly corresponds to the arc-path command of SVG) +is used to add an arc to the path that starts at the current point and +ends at ⟨target point⟩. This arc is part of an ellipse that is +determined in the following way: Imagine an ellipse with radii +⟨x-radius⟩ and ⟨y-radius⟩ that is rotated around its center by +⟨rotation⟩ degrees. When you move this ellipse around in the plane, +there will be exactly two positions such that the two current point and +the target point lie on the border of the ellipse (excluding +pathological cases). The flags ⟨large arc flag⟩ and ⟨clockwise flag⟩ are +then used to decide which of these ellipses should be picked and which +arc on the picked ellipsis should be used. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \pgfpathmoveto{\pgfpoint{0mm}{20mm}} + \pgfpatharcto{3cm}{1cm}{0}{0}{0}{\pgfpoint{3cm}{1cm}} + \pgfusepath{draw} + \end{tikzpicture} + +Both flags are considered to be false exactly if they evaluate to `0`, +otherwise they are true. If the ⟨large arc flag⟩ is true, then the angle +spanned by the arc will be greater than $180^\circ$, otherwise it will +be less than $180^\circ$. The ⟨clockwise flag⟩ is used to determine +which of the two ellipses should be used: if the flag is true, then the +arc goes from the current point to the target point in a +counterclockwise direction, otherwise in a clockwise fashion. + + \begin{tikzpicture} + \pgfsetlinewidth{2pt} + % Flags 0 0: red + \pgfsetstrokecolor{red} + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharcto{20pt}{10pt}{0}{0}{0}{\pgfpoint{20pt}{10pt}} + \pgfusepath{stroke} + % Flags 0 1: blue + \pgfsetstrokecolor{blue} + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharcto{20pt}{10pt}{0}{0}{1}{\pgfpoint{20pt}{10pt}} + \pgfusepath{stroke} + % Flags 1 0: orange + \pgfsetstrokecolor{orange} + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharcto{20pt}{10pt}{0}{1}{0}{\pgfpoint{20pt}{10pt}} + \pgfusepath{stroke} + % Flags 1 1: black + \pgfsetstrokecolor{black} + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharcto{20pt}{10pt}{0}{1}{1}{\pgfpoint{20pt}{10pt}} + \pgfusepath{stroke} + \end{tikzpicture} + +*Warning:* The internal computations necessary for this command are +numerically very unstable. In particular, the arc will not always really +end at the ⟨target coordinate⟩, but may be off by up to several points. +A more precise positioning is currently infeasible due to TeX's +numerical weaknesses. The only case it works quite nicely is when the +resulting angle is a multiple of $90^\circ$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpatharcto" + }, + pgfpatharctomaxstepsize = { + details = [[ +The quality of arc approximation taken by `\pgfpatharctoprecomputed` by +means of Bézier splines is controlled by a mesh width, which is +initially + +`\def\pgfpatharctoprecomputed{45}`. + +The mesh width is provided in (full!) degrees. The smaller the mesh +width, the more precise the arc approximation. + +Use an empty value to disable spline approximation (uses a single cubic +polynomial for the complete arc). + +The value must be an integer! +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpatharctomaxstepsize" + }, + pgfpatharctoprecomputed = { + arguments = { + {meta = "center point"}, + {meta = "start angle"}, + {meta = "end angle"}, + {meta = "end point"}, + {meta = "x-radius"}, + {meta = "y-radius"}, + {meta = "ratio x-radius/y-radius"}, + {meta = "ratio y-radius/x-radius"} + }, + details = [[ +A specialized arc operation which is fast and numerically stable, +provided a lot of information is given in advance. + +In contrast to `\pgfpatharc`, it explicitly interpolates start and end +points. + +In contrast to `\pgfpatharcto`, this routine is numerically stable and +quite fast since it relies on a lot of available information. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \def\cx{1.5cm}% center x + \def\cy{1cm}% center y + \def\startangle{0}% + \def\endangle{270}% + \def\a{1.5cm}% xradius + \def\b{0.5cm}% yradius + \pgfmathparse{\a/\b}\let\abratio=\pgfmathresult + \pgfmathparse{\b/\a}\let\baratio=\pgfmathresult + % + % start point: + \pgfpathmoveto{\pgfpoint{\cx+\a*cos(\startangle)}{\cy+\b*sin(\startangle)}}% + \pgfpatharctoprecomputed + {\pgfpoint{\cx}{\cy}} + {\startangle} + {\endangle} + {\pgfpoint{\cx+\a*cos(\endangle)}{\cy+\b*sin(\endangle)}}% end point + {\a} + {\b} + {\abratio} + {\baratio} + \pgfusepath{draw} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpatharctoprecomputed" + }, + pgfpathcircle = { + arguments = {{meta = "center"}, {meta = "radius"}}, + details = [[ +A shorthand for `\pgfpathellipse` applied to ⟨center⟩ and the two axis +vectors $(⟨radius⟩,0)$ and $(0,⟨radius⟩)$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathcircle" + }, + pgfpathclose = { + details = [[ +This command closes the current part of the path by appending a straight +line to the start point of the current part. Note that there *is* a +difference between closing a path and using the line-to operation to add +a straight line to the start of the current path. The difference is +demonstrated by the upper corners of the triangles in the following +example: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{5pt} + \pgfpathmoveto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{0cm}{-1cm}} + \pgfpathlineto{\pgfpoint{1cm}{-1cm}} + \pgfpathclose + \pgfpathmoveto{\pgfpoint{2.5cm}{1cm}} + \pgfpathlineto{\pgfpoint{1.5cm}{-1cm}} + \pgfpathlineto{\pgfpoint{2.5cm}{-1cm}} + \pgfpathlineto{\pgfpoint{2.5cm}{1cm}} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathclose" + }, + pgfpathcosine = { + arguments = {{meta = "vector"}}, + details = [[ +This command appends a cosine curve in the interval $[0,\pi/2]$ to the +current path. The curve is squeezed or stretched such that the curve +starts at the current point and ends at the current point plus ⟨vector⟩. +Using several sine and cosine operations in sequence allows you to +produce a complete sine or cosine curve + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpoint{0cm}{0cm}} + \pgfpathsine{\pgfpoint{1cm}{1cm}} + \pgfpathcosine{\pgfpoint{1cm}{-1cm}} + \pgfpathsine{\pgfpoint{1cm}{-1cm}} + \pgfpathcosine{\pgfpoint{1cm}{1cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + +The command will apply coordinate transformations and update the +bounding boxes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathcosine" + }, + pgfpathcurvebetweentime = { + arguments = { + {meta = "time $t_1$"}, + {meta = "time $t_2$"}, + {meta = "point p"}, + {meta = "point $s_1$"}, + {meta = "point $s_2$"}, + {meta = "point q"} + }, + details = [[ +This command draws the part of the curve described by $p$, $s_1$, $s_2$ +and $q$ between the times $t_1$ and $t_2$. A time value of 0 indicates +the point $p$ and a time value of 1 indicates point $q$. This command +includes a moveto operation to the first point. + + \begin{tikzpicture} + \draw [thin] (0,0) .. controls (0,2) and (3,0) .. (3,2); + \pgfpathcurvebetweentime{0.25}{0.9}{\pgfpointxy{0}{0}}{\pgfpointxy{0}{2}} + {\pgfpointxy{3}{0}}{\pgfpointxy{3}{2}} + \pgfsetstrokecolor{red} + \pgfsetstrokeopacity{0.5} + \pgfsetlinewidth{2pt} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathcurvebetweentime" + }, + pgfpathcurvebetweentimecontinue = { + arguments = { + {meta = "time $t_1$"}, + {meta = "time $t_2$"}, + {meta = "point p"}, + {meta = "point $s_1$"}, + {meta = "point $s_2$"}, + {meta = "point q"} + }, + details = [[ +This command works like `\pgfpathcurvebetweentime`, except that a moveto +operation is *not* made to the first point. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathcurvebetweentimecontinue" + }, + pgfpathcurveto = { + arguments = {{meta = "support 1"}, {meta = "support 2"}, {meta = "coordinate"}}, + details = [[ +This command extends the current path with a Bézier curve from the last +point of the path to ⟨coordinate⟩. The ⟨support 1⟩ and ⟨support 2⟩ are +the first and second support point of the Bézier curve. For more +information on Bézier curves, please consult a standard textbook on +computer graphics. + +Like the line-to command, this command may not be the first path +construction command in a path. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{1cm}}{\pgfpoint{3cm}{0cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + +The command will apply the current coordinate transformation matrix to +⟨coordinate⟩ before using it. + +It will update the bounding box of the current path and picture, if +necessary. However, the bounding box is simply made large enough such +that it encompasses all of the support points and the ⟨coordinate⟩. This +will guarantee that the curve is completely inside the bounding box, but +the bounding box will typically be quite a bit too large. It is not +clear (to me) how this can be avoided without resorting to "some serious +math" in order to calculate a precise bounding box. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathcurveto" + }, + pgfpathellipse = { + arguments = {{meta = "center"}, {meta = "first axis"}, {meta = "second axis"}}, + details = [[ +The effect of this command is to append an ellipse to the current path +(if the path is not empty, a new part is started). The ellipse's center +will be ⟨center⟩ and ⟨first axis⟩ and ⟨second axis⟩ are the axis +*vectors*. The same effect as this command can also be achieved using an +appropriate sequence of move-to, arc, and close operations, but this +command is easier and faster. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathellipse{\pgfpoint{1cm}{0cm}} + {\pgfpoint{1.5cm}{0cm}} + {\pgfpoint{0cm}{1cm}} + \pgfusepath{draw} + \color{red} + \pgfpathellipse{\pgfpoint{1cm}{0cm}} + {\pgfpoint{1cm}{1cm}} + {\pgfpoint{-0.5cm}{0.5cm}} + \pgfusepath{draw} + \end{tikzpicture} + +The command will apply coordinate transformations to all coordinates of +the ellipse. However, the coordinate transformations are applied only +after the ellipse is "finished conceptually". Thus, a transformation of +1cm to the right will simply shift the ellipse one centimeter to the +right; it will not add 1cm to the $x$-coordinates of the two axis +vectors. + +The command will update the bounding box of the current path and +picture, if necessary. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathellipse" + }, + pgfpathgrid = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "first corner"}, + {meta = "second corner"} + }, + details = [[ +Appends a grid to the current path. That is, a (possibly large) number +of parts are added to the path, each part consisting of a single +horizontal or vertical straight line segment. + +Conceptually, the origin is part of the grid and the grid is clipped to +the rectangle specified by the ⟨first corner⟩ and the ⟨second corner⟩. +However, no clipping occurs (this command just adds parts to the current +path) and the points where the lines enter and leave the "clipping area" +are computed and used to add simple lines to the current path. + +The following keys influence the grid: + + \begin{pgfpicture} + \pgfsetlinewidth{0.8pt} + \pgfpathgrid[step={\pgfpoint{1cm}{1cm}}] + {\pgfpoint{-3mm}{-3mm}}{\pgfpoint{33mm}{23mm}} + \pgfusepath{stroke} + \pgfsetlinewidth{0.4pt} + \pgfpathgrid[stepx=1mm,stepy=1mm] + {\pgfpoint{-1.5mm}{-1.5mm}}{\pgfpoint{31.5mm}{21.5mm}} + \pgfusepath{stroke} + \end{pgfpicture} + +The command will apply coordinate transformations and update the +bounding boxes. As for ellipses, the transformations are applied to the +"conceptually finished" grid. + + \begin{pgfpicture} + \pgftransformrotate{10} + \pgfpathgrid[stepx=1mm,stepy=2mm]{\pgfpoint{0mm}{0mm}}{\pgfpoint{30mm}{30mm}} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathgrid" + }, + pgfpathlineto = { + arguments = {{meta = "coordinate"}}, + details = [[ +This command extends the current path in a straight line to the given +⟨coordinate⟩. If this command is given at the beginning of path without +any other path construction command given before (in particular without +a move-to operation), the TeX file may compile without an error message, +but a viewer application may display an error message when trying to +render the picture. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + +The command will apply the current coordinate transformation matrix to +⟨coordinate⟩ before using it. + +It will update the bounding box of the current path and picture, if +necessary. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathlineto" + }, + pgfpathmoveto = { + arguments = {{meta = "coordinate"}}, + details = [[ +This command expects a PGF-coordinate like `\pgfpointorigin` as its +parameter. When the current path is empty, this operation will start the +path at the given ⟨coordinate⟩. If a path has already been partly +constructed, this command will end the current part of the path and +start a new one. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}} + \pgfpathlineto{\pgfpoint{3cm}{0.5cm}} + \pgfpathlineto{\pgfpoint{3cm}{0cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}} + \pgfpathmoveto{\pgfpoint{2cm}{1cm}} % New part + \pgfpathlineto{\pgfpoint{3cm}{0.5cm}} + \pgfpathlineto{\pgfpoint{3cm}{0cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + +The command will apply the current coordinate transformation matrix to +⟨coordinate⟩ before using it. + +It will update the bounding box of the current path and picture, if +necessary. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathmoveto" + }, + pgfpathparabola = { + arguments = {{meta = "bend vector"}, {meta = "end vector"}}, + details = [[ +This command appends two half-parabolas to the current path. The first +starts at the current point and ends at the current point plus ⟨bend +vector⟩. At this point, it has its bend. The second half parabola starts +at that bend point and ends at point that is given by the bend plus ⟨end +vector⟩. + +If you set ⟨end vector⟩ to the null vector, you append only a half +parabola that goes from the current point to the bend; by setting ⟨bend +vector⟩ to the null vector, you append only a half parabola that goes +through the current point and ⟨end vector⟩ and has its bend at the +current point. + +It is not possible to use this command to draw a part of a parabola that +does not contain the bend. + + \begin{pgfpicture} + % Half-parabola going ``up and right'' + \pgfpathmoveto{\pgfpointorigin} + \pgfpathparabola{\pgfpointorigin}{\pgfpoint{2cm}{4cm}} + \color{red} + \pgfusepath{stroke} + + % Half-parabola going ``down and right'' + \pgfpathmoveto{\pgfpointorigin} + \pgfpathparabola{\pgfpoint{-2cm}{4cm}}{\pgfpointorigin} + \color{blue} + \pgfusepath{stroke} + + % Full parabola + \pgfpathmoveto{\pgfpoint{-2cm}{2cm}} + \pgfpathparabola{\pgfpoint{1cm}{-1cm}}{\pgfpoint{2cm}{4cm}} + \color{orange} + \pgfusepath{stroke} + \end{pgfpicture} + +The command will apply coordinate transformations and update the +bounding boxes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathparabola" + }, + pgfpathqcircle = { + arguments = {{meta = "radius"}}, + details = [[ +Adds a radius around the origin of the given ⟨radius⟩. This command is +orders of magnitude faster than +`\pgfcircle{\pgfpointorigin}{`⟨radius⟩`}`. + + \colorlet{examplefill}{yellow!80!black} + \begin{tikzpicture} + \draw[help lines] (0,0) grid (1,1); + \pgfpathqcircle{10pt} + \pgfsetfillcolor{examplefill} + \pgfusepath{stroke,fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathqcircle" + }, + pgfpathqcurveto = { + arguments = { + {meta = "$s^1_x$"}, + {meta = "$s^1_y$"}, + {meta = "$s^2_x$"}, + {meta = "$s^2_y$"}, + {meta = "$t_x$"}, + {meta = "$t_y$"} + }, + details = [[ +The quick version of the curve-to operation. The first support point is +$(s^1_x,s^1_y)$, the second support point is $(s^2_x,s^2_y)$, and the +target is $(t_x,t_y)$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathqmoveto{0pt}{0pt} + \pgfpathqcurveto{1cm}{1cm}{2cm}{1cm}{3cm}{0cm} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathqcurveto" + }, + pgfpathqlineto = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ +The quick version of the line-to operation. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathqlineto" + }, + pgfpathqmoveto = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ +Either starts a path or starts a new part of a path at the coordinate +$(⟨x dimension⟩,⟨y dimension⟩)$. The coordinate is *not* transformed by +the current coordinate transformation matrix. However, any low-level +transformations apply. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformxshift{1cm} + \pgfpathqmoveto{0pt}{0pt} % not transformed + \pgfpathqlineto{1cm}{1cm} % not transformed + \pgfpathlineto{\pgfpoint{2cm}{0cm}} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathqmoveto" + }, + pgfpathquadraticcurveto = { + arguments = {{meta = "support"}, {meta = "coordinate"}}, + details = [[ +This command works like `\pgfpathcurveto`, only it uses a quadratic +Bézier curve rather than a cubic one. This means that only one support +point is needed. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathquadraticcurveto + {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{0cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + +Internally, the quadratic curve is converted into a cubic curve. The +only noticeable effect of this is that the points used for computing the +bounding box are the control points of the converted curve rather than +⟨support⟩. The main effect of this is that the bounding box will be a +bit tighter than might be expected. In particular, ⟨support⟩ will not +always be part of the bounding box. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathquadraticcurveto" + }, + pgfpathrectangle = { + arguments = {{meta = "corner"}, {meta = "diagonal vector"}}, + details = [[ +Adds a rectangle to the path whose one corner is ⟨corner⟩ and whose +opposite corner is given by $⟨corner⟩ + ⟨diagonal vector⟩$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathrectangle{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1.5cm}{0.25cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfpathrectangle{\pgfpoint{2cm}{0.5cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfusepath{draw} + \end{tikzpicture} + +The command will apply coordinate transformations and update the +bounding boxes tightly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathrectangle" + }, + pgfpathrectanglecorners = { + arguments = {{meta = "corner"}, {meta = "opposite corner"}}, + details = [[ +Adds a rectangle to the path whose two opposing corners are ⟨corner⟩ and +⟨opposite corner⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathrectanglecorners{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfusepath{draw} + \end{tikzpicture} + +The command will apply coordinate transformations and update the +bounding boxes tightly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathrectanglecorners" + }, + pgfpathsine = { + arguments = {{meta = "vector"}}, + details = [[ +This command appends a sine curve in the interval $[0,\pi/2]$ to the +current path. The sine curve is squeezed or stretched such that the +curve starts at the current point and ends at the current point plus +⟨vector⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,1); + \pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathsine{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} + + \color{red} + \pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathsine{\pgfpoint{-2cm}{-2cm}} + \pgfusepath{stroke} + \end{tikzpicture} + +The command will apply coordinate transformations and update the +bounding boxes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathsine" + }, + pgfpathsvg = { + arguments = {{meta = "path"}}, + details = [[ +This command extends the current path by a ⟨path⟩ given in the +SVG-path-data syntax. This syntax is described in detail in Section 8.3 +of the SVG-specification, Version 1.1. + +In principle, the complete syntax is supported and the library just +provides a parser and a mapping to basic layer commands. For instance, +`M 0 10` is mapped to `\pgfpathmoveto{\pgfpoint{0pt}{10pt}}`. There are, +however, a few things to be aware of: + +- The computation underlying the arc commands `A` and `a` are not + numerically stable, which may result in quite imprecise arcs. Bézier + curves, both quadratic and cubic, are not affected, neither are arcs + spanning degrees that are multiples of $90^{\circ}$. + +- The dimensionless units of SVG are always interpreted as points + (`pt`). This is a problem with paths like `M 20000 0`, which will + raise an error message since TeX cannot handle dimensions larger + than about 16 000 points. + +- All coordinate and canvas transformations apply to the path in the + usual fashion. + +- The `\pgfpathsvg` command can be freely intermixed with other path + commands. + + + + \begin{pgfpicture} + \pgfpathsvg{M 0 0 l 20 0 0 20 -20 0 q 10 0 10 10 + t 10 10 10 10 h -50 z} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathsvg" + }, + pgfplotbarwidth = { + details = [[ +Expands to the value of `/pgf/bar width`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotbarwidth" + }, + pgfplotfunction = { + arguments = {{meta = "variable"}, {meta = "sample list"}, {meta = "point"}}, + details = [[ +This command will produce coordinates by iterating the ⟨variable⟩ over +all values in ⟨sample list⟩, which should be a list in the `\foreach` +syntax. For each value of ⟨variable⟩, the ⟨point⟩ is evaluated and the +resulting coordinate is inserted into the plot stream. + + \begin{tikzpicture}[x=3.8cm/360] + \pgfplothandlerlineto + \pgfplotfunction{\x}{0,5,...,360}{\pgfpointxy{\x}{sin(\x)+sin(3*\x)}} + \pgfusepath{stroke} + \end{tikzpicture} + + \begin{tikzpicture}[y=3cm/360] + \pgfplothandlerlineto + \pgfplotfunction{\y}{0,5,...,360}{\pgfpointxyz{sin(2*\y)}{\y}{cos(2*\y)}} + \pgfusepath{stroke} + \end{tikzpicture} + +Be warned that if the expressions that need to evaluated for each point +are complex, then this command can be very slow. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotfunction" + }, + pgfplotgnuplot = { + arguments = { + {delimiters = {"[", "]"}, meta = "prefix", optional = true}, + {meta = "function"} + }, + details = [[ +This command will "try" to call the GNUPLOT program to generate the +coordinates of the ⟨function⟩. In detail, the following happens: + +This command works with two files: ⟨prefix⟩`.gnuplot` and +⟨prefix⟩`.table`. If the optional argument ⟨prefix⟩ is not given, it is +set to `\jobname`. + +Let us start with the situation where none of these files exists. Then +PGF will first generate the file ⟨prefix⟩`.gnuplot`. In this file it +writes + + set table "#1.table"; set format "%.5f" + +where `# 1` is replaced by ⟨prefix⟩. Then, in a second line, it writes +the text ⟨function⟩. + +Next, PGF will try to invoke the program `gnuplot` with the argument +⟨prefix⟩`.gnuplot`. This call may or may not succeed, depending on +whether the `\write18` mechanism (also known as shell escape) is +switched on and whether the `gnuplot` program is available. + +Assuming that the call succeeded, the next step is to invoke +`\pgfplotxyfile` on the file ⟨prefix⟩`.table`; which is exactly the file +that has just been created by `gnuplot`. + + \begin{tikzpicture} + \draw[help lines] (0,-1) grid (4,1); + \pgfplothandlerlineto + \pgfplotgnuplot[plots/pgfplotgnuplot-example]{plot [x=0:3.5] x*sin(x)} + \pgfusepath{stroke} + \end{tikzpicture} + +The more difficult situation arises when the `.gnuplot` file exists, +which will be the case on the second run of TeX on the TeX file. In this +case PGF will read this file and check whether it contains exactly what +PGF "would have written" into this file. If this is not the case, the +file contents is overwritten with what "should be there" and, as above, +`gnuplot` is invoked to generate a new `.table` file. However, if the +file contents is "as expected", the external `gnuplot` program is *not* +called. Instead, the ⟨prefix⟩`.table` file is immediately read. + +As explained in Section ??, the net effect of the above mechanism is +that `gnuplot` is called as seldom as possible and that when you pass +along the `.gnuplot` and `.table` files with your `.tex` file to someone +else, that person can TeX the `.tex` file without having `gnuplot` +installed and without having the `\write18` mechanism switched on. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotgnuplot" + }, + pgfplothandlerclosedcurve = { + details = [[ +This handler works like the curve-to plot handler, only it will add a +new part to the current path that is a closed curve through the plot +points. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerclosedcurve + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerclosedcurve" + }, + pgfplothandlerconstantlineto = { + details = [[ +This handler works like the line-to plot handler, only it will produce a +connected, piecewise constant path to connect the points. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerconstantlineto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerconstantlineto" + }, + pgfplothandlerconstantlinetomarkmid = { + details = [[ +A variant of `\pgfplothandlerconstantlineto` which places its mark on +the center of the line. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerconstantlinetomarkmid + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} + +The plot handler always connects two data points by a horizontal line +starting from the previous data points, followed by a vertical line in +the middle between the two data points, followed by a horizontal line +between the middle and the current data point. This results in a +symmetric constant plot handler for constant mesh width. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerconstantlinetomarkmid" + }, + pgfplothandlerconstantlinetomarkright = { + details = [[ +A variant of `\pgfplothandlerconstantlineto` which places its mark on +the right line ends. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerconstantlinetomarkright + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerconstantlinetomarkright" + }, + pgfplothandlercurveto = { + details = [[ +This handler will issue a `\pgfpathcurveto` command for each point of +the plot, *except* possibly for the first. As for the line-to handler, +what happens with the first point can be specified using +`\pgfsetmovetofirstplotpoint` or `\pgfsetlinetofirstplotpoint`. + +Obviously, the `\pgfpathcurveto` command needs, in addition to the +points on the path, some control points. These are generated +automatically using a somewhat "dumb" algorithm: Suppose you have three +points $x$, $y$, and $z$ on the curve such that $y$ is between $x$ and +$z$: + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlercurveto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} + +In order to determine the control points of the curve at the point $y$, +the handler computes the vector $z-x$ and scales it by the tension +factor (see below). Let us call the resulting vector $s$. Then $y+s$ and +$y-s$ will be the control points around $y$. The first control point at +the beginning of the curve will be the beginning itself, once more; +likewise the last control point is the end itself. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlercurveto" + }, + pgfplothandlerdiscard = { + details = [[ +This handler will simply throw away the stream. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerdiscard" + }, + pgfplothandlergapcycle = { + details = [[ +Works like `\pgfplothandlergaplineto`, but the last point is connected +to the first in the same fashion: + + \begin{tikzpicture} + \pgfplothandlergapcycle + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlergapcycle" + }, + pgfplothandlergaplineto = { + details = [[ +This handler will connect the points of the plots by straight line +segments. However, at the start and the end of the lines there will be a +small gap, given by the following key: + + \begin{tikzpicture} + \pgfplothandlergaplineto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlergaplineto" + }, + pgfplothandlerjumpmarkleft = { + details = [[ +This handler works like the line-to plot handler, only it will produce a +non-connected, piecewise constant path to connect the points. If there +are any plot marks, they will be placed on the left open pieces. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerjumpmarkleft + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerjumpmarkleft" + }, + pgfplothandlerjumpmarkmid = { + details = [[ +This handler works like the `\pgfplothandlerconstantlinetomarkmid`, but +it will produce a non-connected, piecewise constant path to connect the +points. If there are any plot marks, they will be placed in the center +of the horizontal line segment.. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerjumpmarkmid + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} + +See `\pgfplothandlerconstantlinetomarkmid` for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerjumpmarkmid" + }, + pgfplothandlerjumpmarkright = { + details = [[ +This handler works like the line-to plot handler, only it will produce a +non-connected, piecewise constant path to connect the points. If there +are any plot marks, they will be placed on the right open pieces. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerjumpmarkright + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerjumpmarkright" + }, + pgfplothandlerlineto = { + details = [[ +This handler will issue a `\pgfpathlineto` command for each point of the +plot, *except* possibly for the first. What happens with the first point +can be specified using the two commands described below. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfplothandlerlineto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{3cm}{2cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerlineto" + }, + pgfplothandlermark = { + arguments = {{meta = "mark code"}}, + details = [[ +This command will execute the ⟨mark code⟩ for some points of the plot, +but each time the coordinate transformation matrix will be set up such +that the origin is at the position of the point to be plotted. This way, +if the ⟨mark code⟩ draws a little circle around the origin, little +circles will be drawn at some point of the plot. + +By default, a mark is drawn at all points of the plot. However, two +parameters $r$ and $p$ influence this. First, only every $r$th mark is +drawn. Second, the first mark drawn is the $p$th. These parameters can +be influenced using the commands below. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} + +Typically, the ⟨code⟩ will be `\pgfuseplotmark{`⟨plot mark name⟩`}`, +where ⟨plot mark name⟩ is the name of a predefined plot mark. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlermark" + }, + pgfplothandlermarklisted = { + arguments = {{meta = "mark code"}, {meta = "index list"}}, + details = [[ +This command works similar to the previous one. However, marks will only +be placed at those indices in the given ⟨index list⟩. The syntax for the +list is the same as for the `\foreach` statement. For example, if you +provide the list `1,3,...,25`, a mark will be placed only at every +second point. Similarly, `1,2,4,8,16,32` yields marks only at those +points that are powers of two. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermarklisted + {\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}} + {1,3} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlermarklisted" + }, + pgfplothandlerpolarcomb = { + details = [[ +This handler converts each point in the plot stream into a line from the +origin to the point's coordinate. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerpolarcomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerpolarcomb" + }, + pgfplothandlerpolygon = { + details = [[ +This handler works like the line-to plot handler, only the line is +closed at the end using `\pgfpathclose`, resulting in a polygon. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerpolygon" + }, + pgfplothandlerrecord = { + arguments = {{meta = "macro"}}, + details = [[ +When this handler is installed, each time a plot stream command is +called, this command will be appended to ⟨macro⟩. Thus, at the end of +the stream, ⟨macro⟩ will contain all the commands that were issued on +the stream. You can then install another handler and invoke ⟨macro⟩ to +"replay" the stream (possibly many times). + + \begin{pgfpicture} + \pgfplothandlerrecord{\mystream} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{3cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} + \pgfplotstreamend + \pgfplothandlerlineto + \mystream + \pgfplothandlerclosedcurve + \mystream + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerrecord" + }, + pgfplothandlerxbar = { + details = [[ +This handler converts each point in the plot stream into a rectangle +from the $y$-axis to the point's coordinate. The rectangle is placed +centered at the $y$-axis. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerxbar + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerxbar" + }, + pgfplothandlerxbarinterval = { + details = [[ +As `\pgfplothandlerybarinterval`, this handler provides bar plots with +relative bar sizes and offsets, one bar for each $y$ coordinate +interval. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerxbarinterval" + }, + pgfplothandlerxcomb = { + details = [[ +This handler converts each point in the plot stream into a line from the +$y$-axis to the point's coordinate, resulting in a "horizontal comb". + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerxcomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerxcomb" + }, + pgfplothandlerybar = { + details = [[ +This handler converts each point in the plot stream into a rectangle +from the $x$-axis to the point's coordinate. The rectangle is placed +centered at the $x$-axis. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerybar + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerybar" + }, + pgfplothandlerybarinterval = { + details = [[ +This handler is a variant of `\pgfplothandlerybar` which works with +intervals instead of points. + +Bars are drawn between successive input coordinates and the width is +determined relatively to the interval length. + + \begin{tikzpicture} + \draw[gray] (0,2) node {$x_1$} (1,1) node {$x_2$} (2,.5) node {$x_3$} (4,0.7) node {$x_4$}; + \pgfplothandlerybarinterval + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{2cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} + +In more detail, if $(x_i,y_i)$ and $(x_{i+1},y_{i+1})$ denote successive +input coordinates, the bar will be placed above the interval +$[x_i,x_{i+1}]$, centered at +$$x_i + ⟨bar interval shift⟩ \cdot (x_{i+1} - x_i)$$ with width +$$⟨bar interval width⟩ \cdot (x_{i+1} - x_i).$$ Here, ⟨bar interval +shift⟩ and ⟨bar interval width⟩ denote the current values of the +associated options. + +If you have $N+1$ input points, you will get $N$ bars (one for each +interval). The $y$ value of the last point will be ignored. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerybarinterval" + }, + pgfplothandlerycomb = { + details = [[ +This handler converts each point in the plot stream into a line from the +$x$-axis to the point's coordinate, resulting in a "vertical comb". + +This handler is useful for creating "bar diagrams". + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerycomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerycomb" + }, + pgfplotstreamend = { + details = [[ +This command signals that a plot stream ends. It calls +`\pgf@plotstreamend`, which should now do any necessary "cleanup". +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreamend" + }, + pgfplotstreamnewdataset = { + details = [[ +This command indicated that in the stream a "new data set" starts. So, +the stream does not end, but there is a logical break in the data. For +example, when a table is read from a file, empty lines are interpreted +as indicating new data sets. What happens when a new data set is +encountered is governed by the following key: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreamnewdataset" + }, + pgfplotstreampoint = { + arguments = {{meta = "point"}}, + details = [[ +This command adds a ⟨point⟩ to the current plot stream. The effect of +this command is to call the internal command `\pgf@plotstreampoint`, +which is also set by the current plot handler. This command should now +"handle" the point in some sensible way. For example, a line-to command +might be issued for the point. + +When a plot handler is installed, it will setup the internal command +`\pgf@plotstreampoint` in some way. It is permissible to change the +meaning of this internal command during a stream. For instance, a +handler might setup `\pgf@plotstreampoint` in some sensible way for the +first point and then redefine it so that subsequent points are handled +in some other way. + +As mentioned earlier, the `\pgfplotstreamstart` will always reset the +definition of the internal command to the initial meaning it had when +the handler was installed. This is true for the other commands mentioned +in the following. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreampoint" + }, + pgfplotstreampointoutlier = { + arguments = {{meta = "point"}}, + details = [[ +An *outlier* is a point that is "out of bounds" in some way. For +instance, it might have very large coordinates or the coordinates might +just be outside some specified range. Nevertheless, an outlier is still +a well-defined point. This command is issued, for instance, by GNUPLOT +when a value is outside the specified range. + +You can configure how outliers are treated using the following key: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreampointoutlier" + }, + pgfplotstreampointundefined = { + details = [[ +This command indicated that the stream contains an "undefined" point +like a point where some coordinate results for a division by zero. Such +a point cannot be plotted, which is why it is not given as a parameter. +However, such a point *can* result in a jump in the plot, depending on +the setting of the following key: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreampointundefined" + }, + pgfplotstreamspecial = { + arguments = {{meta = "text"}}, + details = [[ +This command causes `\pgf@plotstreamspecial` to be called with ⟨text⟩ as +its parameter. This allows handler-specific information to be passed to +the handler. All normal handlers ignore this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreamspecial" + }, + pgfplotstreamstart = { + details = [[ +This command signals that a plot stream starts. The effect of this +command is to call the internal command `\pgf@plotstreamstart`, which is +set by the current plot handler to do whatever needs to be done at the +beginning of the plot. It will also reset the meaning of the internal +commands like `\pgf@plotstreampoint` to the initial setting for the plot +handler (what this means will be explained in a moment). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreamstart" + }, + pgfplotxyfile = { + arguments = {{meta = "filename"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotxyfile" + }, + pgfplotxyzfile = { + arguments = {{meta = "filename"}}, + details = [[ +This command works like `\pgfplotxyfile`, only *three* numbers are +expected on each non-empty line. They are converted into points in the +$xyz$-coordinate system. Consider, the following file: + + % Some comments + # more comments + 2 -5 1 first entry + 2 -.2 2 o + 2 -5 2 third entry + +It is turned into the following stream: + + \pgfplotstreamstart + \pgfplotstreamnewdataset + \pgfplotstreamnewdataset + \pgfplotstreampoint{\pgfpointxyz{2}{-5}{1}} + \pgfplotstreampointoutlier{\pgfpointxyz{2}{-.2}{2}} + \pgfplotstreampoint{\pgfpointxyz{2}{-5}{2}} + \pgfplotstreamend +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotxyzfile" + }, + pgfplotxzerolevelstreamconstant = { + arguments = {{meta = "dimension"}}, + details = [[ +This zero level stream always returns `{dimension}` instead of $x=0$pt. + +It is used for `xcomb` and `xbar`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotxzerolevelstreamconstant" + }, + pgfplotyzerolevelstreamconstant = { + arguments = {{meta = "dimension"}}, + details = [[ +This zero level stream always returns `{dimension}` instead of $y=0$pt. + +It is used for `ycomb` and `ybar`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotyzerolevelstreamconstant" + }, + pgfpoint = { + arguments = {{meta = "x coordinate"}, {meta = "y coordinate"}}, + details = [[ +Yields a point location. The coordinates are given as TeX dimensions. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpoint{1cm}{1cm}} {2pt} + \pgfpathcircle{\pgfpoint{2cm}{5pt}} {2pt} + \pgfpathcircle{\pgfpoint{0pt}{.5in}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpoint" + }, + pgfpointadd = { + arguments = {{meta = "$v_1$"}, {meta = "$v_2$"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointadd" + }, + pgfpointanchor = { + arguments = {{meta = "node"}, {meta = "anchor"}}, + details = [[ +This command is another "point command" like the commands described in +Section ??. It returns the coordinate of the given ⟨anchor⟩ in the given +⟨node⟩. The command can be used in commands like `\pgfpathmoveto`. + + \begin{pgfpicture} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + + \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt} + \pgfusepath{fill} + \end{pgfpicture} + +In the above example, you may have noticed something curious: The +rotation transformation is still in force when the anchors are invoked, +but it does not seem to have an effect. You might expect that the +rotation should apply to the already rotated points once more. + +However, `\pgfpointanchor` returns a point that takes the current +transformation matrix into account: *The inverse transformation to the +current coordinate transformation is applied to an anchor point before +returning it.* + +This behavior may seem a bit strange, but you will find it very natural +in most cases. If you really want to apply a transformation to an anchor +point (for example, to "shift it away" a little bit), you have to invoke +`\pgfpointanchor` without any transformations in force. Here is an +example: + + \begin{pgfpicture} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + + { + \pgftransformreset + \pgfpointanchor{x}{east} + \xdef\mycoordinate{\noexpand\pgfpoint{\the\pgf@x}{\the\pgf@y}} + } + + \pgfpathcircle{\mycoordinate}{2pt} + \pgfusepath{fill} + \end{pgfpicture} + +A special situation arises when the ⟨node⟩ lies in a picture different +from the current picture. In this case, if you have not told PGF that +the picture should be "remembered", the ⟨node⟩ will be treated as if it +lay in the current picture. For example, if the ⟨node⟩ was at position +$(3,2)$ in the original picture, it is treated as if it lay at position +$(3,2)$ in the current picture. However, if you have told PGF to +remember the picture position of the node's picture and also of the +current picture, then `\pgfpointanchor` will return a coordinate that +corresponds to the position of the node's anchor on the page, +transformed into the current coordinate system. For examples and more +details see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointanchor" + }, + pgfpointarcaxesattime = { + arguments = { + {meta = "time $t$"}, + {meta = "center"}, + {meta = "0-degree axis"}, + {meta = "90-degree axis"}, + {meta = "start angle"}, + {meta = "end angle"} + }, + details = [[ +Yields a point on the arc between ⟨start angle⟩ and ⟨end angle⟩ on an +ellipse whose center is at ⟨center⟩ and whose two principal axes are +⟨0-degree axis⟩ and ⟨90-degree axis⟩. For $t=0$ the point at the ⟨start +angle⟩ is returned and for $t=1$ the point at the ⟨end angle⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpoint{2cm}{1cm}} + \pgfpatharcaxes{0}{60}{\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}} + \pgfusepath{stroke} + \foreach \t in {0,0.25,0.5,0.75,1} + {\pgftext[at=\pgfpointarcaxesattime{\t}{\pgfpoint{0cm}{1cm}} + {\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}}{0}{60}]{\t}} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointarcaxesattime" + }, + pgfpointborderellipse = { + arguments = {{meta = "direction point"}, {meta = "corner"}}, + details = [[ +This command works like the corresponding command for rectangles, only +this time the ⟨corner⟩ is the corner of the bounding rectangle of an +ellipse. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (2,1.5); + \pgfpathellipse{\pgfpointorigin}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{1.25cm}} + \pgfusepath{stroke} + + \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt} + \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt} + \pgfusepath{fill} + \color{red} + \pgfpathcircle{\pgfpointborderellipse + {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfpathcircle{\pgfpointborderellipse + {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointborderellipse" + }, + pgfpointborderrectangle = { + arguments = {{meta = "direction point"}, {meta = "corner"}}, + details = [[ +This command returns a point that lies on the intersection of a line +starting at the origin and going towards the point ⟨direction point⟩ and +a rectangle whose center is in the origin and whose upper right corner +is at ⟨corner⟩. + +The ⟨direction point⟩ should have length "about 1pt", but it will be +normalized automatically. Nevertheless, the "nearer" the length is to +1pt, the less rounding errors. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (2,1.5); + \pgfpathrectanglecorners{\pgfpoint{-1cm}{-1.25cm}}{\pgfpoint{1cm}{1.25cm}} + \pgfusepath{stroke} + + \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt} + \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt} + \pgfusepath{fill} + \color{red} + \pgfpathcircle{\pgfpointborderrectangle + {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfpathcircle{\pgfpointborderrectangle + {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointborderrectangle" + }, + pgfpointcurveattime = { + arguments = { + {meta = "time $t$"}, + {meta = "point $p$"}, + {meta = "point $s_1$"}, + {meta = "point $s_2$"}, + {meta = "point $q$"} + }, + details = [[ +Yields a point that is on the Bézier curve from $p$ to $q$ with the +support points $s_1$ and $s_2$. The time $t$ is used to determine the +location, where $t=0$ yields $p$ and $t=1$ yields $q$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{0cm}{2cm}}{\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} + \foreach \t in {0,0.25,0.5,0.75,1} + {\pgftext[at=\pgfpointcurveattime{\t}{\pgfpointorigin} + {\pgfpoint{0cm}{2cm}} + {\pgfpoint{0cm}{2cm}} + {\pgfpoint{3cm}{2cm}}]{\t}} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointcurveattime" + }, + pgfpointcurvilinearbezierorthogonal = { + arguments = {{meta = "distance"}, {meta = "offset"}}, + details = [[ +This command computes the following point: Consider the curve last +installed using the command `\pgfsetcurvilinearbeziercurve`. We travel +along this curve by ⟨distance⟩, arriving at a point $p$. Then, we turn +by $90^\circ$ and travel by ⟨offset⟩ units "always from the curve", +arriving at a point $q$. This point $q$ will now be returned in `\pgf@x` +and `\pgf@y`; furthermore, the transformed local coordinate system at +point $q$ will also be returned `\pgf@xa` and the other registers, see +`\pgftransformnonlinear` for details. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { + \pgfsetcurvilinearbeziercurve + {\pgfpoint{0mm}{20mm}} + {\pgfpoint{11mm}{20mm}} + {\pgfpoint{20mm}{11mm}} + {\pgfpoint{20mm}{0mm}} + \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}% + \draw (0,-30pt) grid [step=10pt] (80pt,30pt); + } + \draw[red, very thick] + (0mm,20mm) .. controls (11mm,20mm) and (20mm,11mm) .. (20mm,0mm); + \end{tikzpicture} + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { + \pgfsetcurvilinearbeziercurve + {\pgfpoint{0mm}{20mm}} + {\pgfpoint{10mm}{20mm}} + {\pgfpoint{10mm}{10mm}} + {\pgfpoint{20mm}{10mm}} + \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}% + \draw (0,-30pt) grid [step=10pt] (80pt,30pt); + } + \draw[red, very thick] + (0mm,20mm) .. controls (10mm,20mm) and (10mm,10mm) .. (20mm,10mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointcurvilinearbezierorthogonal" + }, + pgfpointcurvilinearbezierpolar = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +This command is similar to the previous version, but the transformation +is different: The idea is that a line form $(0,0)$ to $(x,0)$ gets +transformed to the curve from the start of the curve to a point at +distance $x$ along the curve. This is identical to what the "orthogonal" +transformation above also does. The difference is that a line from +$(0,0)$ to $(0,y)$ gets still transformed to an initial segment of the +curve of a length of $y$, but now rotated by $90^\circ$. In general, the +point $p = (x,y)$ gets transferred to a point that at distance +$\texttt{p} = \sqrt{x^2+y^2}$ along the curve, but rotated by the angle +of $p$ relative to the $x$-axis. + +All of these computations mainly have the following effect: Two straight +lines from the start of the curve as in a `Straight Barb` arrow tip get +transformed to an initial segment of the curve whose length is the +length of the two lines, but this segment gets rotated by the angle of +the two lines. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { + \pgfsetcurvilinearbeziercurve + {\pgfpoint{0mm}{20mm}} + {\pgfpoint{11mm}{20mm}} + {\pgfpoint{20mm}{11mm}} + {\pgfpoint{20mm}{0mm}} + \pgftransformnonlinear{\pgfpointcurvilinearbezierpolar\pgf@x\pgf@y}% + \draw (0,-30pt) grid [step=10pt] (80pt,30pt); + % Add a "barb": + \draw [blue, very thick] (20pt,10pt) -- (0,0) -- (20pt,-10pt); + } + \draw[red, very thick] + (0mm,20mm) .. controls (11mm,20mm) and (20mm,11mm) .. (20mm,0mm); + \end{tikzpicture} + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { + \pgfsetcurvilinearbeziercurve + {\pgfpoint{0mm}{20mm}} + {\pgfpoint{10mm}{20mm}} + {\pgfpoint{10mm}{10mm}} + {\pgfpoint{20mm}{10mm}} + \pgftransformnonlinear{\pgfpointcurvilinearbezierpolar\pgf@x\pgf@y}% + \draw (0,-30pt) grid [step=10pt] (80pt,30pt); + % Add a "barb": + \draw [blue, very thick] (20pt,10pt) -- (0,0) -- (20pt,-10pt); + } + \draw[red, very thick] + (0mm,20mm) .. controls (10mm,20mm) and (10mm,10mm) .. (20mm,10mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointcurvilinearbezierpolar" + }, + pgfpointcylindrical = { + arguments = {{meta = "degree"}, {meta = "radius"}, {meta = "height"}}, + details = [[ +This command yields the same as + + \pgfpointadd{\pgfpointpolarxy{degree}{radius}}{\pgfpointxyz{0}{0}{height}} + + \begin{tikzpicture} + \draw [->] (0,0) -- (1,0,0) node [right] {$x$}; + \draw [->] (0,0) -- (0,1,0) node [above] {$y$}; + \draw [->] (0,0) -- (0,0,1) node [below left] {$z$}; + + \pgfpathcircle{\pgfpointcylindrical{80}{1}{.5}}{2pt} + \pgfusepath{fill} + + \draw[red] (0,0) -- (0,0,.5) -- +(80:1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointcylindrical" + }, + pgfpointdecoratedinputsegmentlast = { + details = [[ +The final point of the current input segment of the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointdecoratedinputsegmentlast" + }, + pgfpointdecoratedpathfirst = { + details = [[ +Returns the point corresponding to the start of the current input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointdecoratedpathfirst" + }, + pgfpointdecoratedpathlast = { + details = [[ +The final point of the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointdecoratedpathlast" + }, + pgfpointdecorationpathlast = { + details = [[ +The final point of the output path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointdecorationpathlast" + }, + pgfpointdiff = { + arguments = {{meta = "start"}, {meta = "end"}}, + details = [[ +Returns the difference vector $⟨end⟩ - ⟨start⟩$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpointdiff{\pgfpoint{1cm}{0cm}}{\pgfpoint{1cm}{1cm}}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointdiff" + }, + pgfpointintersectionofcircles = { + arguments = { + {meta = "$p_1$"}, + {meta = "$p_2$"}, + {meta = "$r_1$"}, + {meta = "$r_2$"}, + {meta = "solution"} + }, + details = [[ +This command returns the intersection of the two circles centered at +$p_1$ and $p_2$ with radii $r_1$ and $r_2$. If ⟨solution⟩ is `1`, the +first intersection is returned, otherwise the second one is returned. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (2,2); + \draw (0.5,0) circle (1); + \draw (1.5,1) circle (.8); + \pgfpathcircle{% + \pgfpointintersectionofcircles + {\pgfpointxy{.5}{0}}{\pgfpointxy{1.5}{1}} + {1cm}{0.8cm}{1}} + {2pt} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointintersectionofcircles" + }, + pgfpointintersectionoflines = { + arguments = {{meta = "$p$"}, {meta = "$q$"}, {meta = "$s$"}, {meta = "$t$"}}, + details = [[ +This command returns the intersection of a line going through $p$ and +$q$ and a line going through $s$ and $t$. If the lines do not +intersection, an arithmetic overflow will occur. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (2,2); + \draw (.5,0) -- (2,2); + \draw (1,2) -- (2,0); + \pgfpathcircle{% + \pgfpointintersectionoflines + {\pgfpointxy{.5}{0}}{\pgfpointxy{2}{2}} + {\pgfpointxy{1}{2}}{\pgfpointxy{2}{0}}} + {2pt} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointintersectionoflines" + }, + pgfpointintersectionsolution = { + arguments = {{meta = "number"}}, + details = [[ +After using the `\pgfintersectionofpaths` command, this command will +return the point for solution ⟨number⟩ or the origin if this solution +was not found. By default, the intersections are simply returned in the +order that the intersection algorithm finds them. Unfortunately, this is +not necessarily a "helpful" ordering. However the following two commands +can be used to order the solutions more helpfully. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointintersectionsolution" + }, + pgfpointlineatdistance = { + arguments = {{meta = "distance"}, {meta = "start point"}, {meta = "end point"}}, + details = [[ +Yields a point that is located ⟨distance⟩ many units away from the start +point in the direction of the end point. In other words, this is the +point that results if we travel ⟨distance⟩ steps from ⟨start point⟩ +towards ⟨end point⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} + \foreach \d in {0pt,20pt,40pt,70pt} + {\pgftext[at= + \pgfpointlineatdistance{\d}{\pgfpointorigin}{\pgfpoint{3cm}{2cm}}]{\d}} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointlineatdistance" + }, + pgfpointlineattime = { + arguments = {{meta = "time $t$"}, {meta = "point $p$"}, {meta = "point $q$"}}, + details = [[ +Yields a point that is the $t$th fraction between $p$ and $q$, that is, +$p + + t(q-p)$. For $t=1/2$ this is the middle of $p$ and $q$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{2cm}{2cm}} + \pgfusepath{stroke} + \foreach \t in {0,0.25,...,1.25} + {\pgftext[at= + \pgfpointlineattime{\t}{\pgfpointorigin}{\pgfpoint{2cm}{2cm}}]{\t}} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointlineattime" + }, + pgfpointmetadecoratedpathfirst = { + details = [[ +When the ⟨before code⟩ is executed, this macro stores the first point on +the current sub-input-path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointmetadecoratedpathfirst" + }, + pgfpointmetadecoratedpathlast = { + details = [[ +When the ⟨after code⟩ is executed, this macro stores the last point on +the current sub-input-path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointmetadecoratedpathlast" + }, + pgfpointnormalised = { + arguments = {{meta = "point"}}, + details = [[ +This command returns a normalised version of ⟨point⟩, that is, a vector +of length 1pt pointing in the direction of ⟨point⟩. If ⟨point⟩ is the +$0$-vector or extremely short, a vector of length 1pt pointing upwards +is returned. + +This command is *not* implemented by calculating the length of the +vector, but rather by calculating the angle of the vector and then using +(something equivalent to) the `\pgfpointpolar` command. This ensures +that the point will really have length 1pt, but it is not guaranteed +that the vector will *precisely* point in the direction of ⟨point⟩ due +to the fact that the polar tables are accurate only up to one degree. +Normally, this is not a problem. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt} + \pgfpathcircle{\pgfpointscale{20} + {\pgfpointnormalised{\pgfpoint{2cm}{1cm}}}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointnormalised" + }, + pgfpointorigin = { + details = [[ +Yields the origin. Same as `\pgfpoint{0pt}{0pt}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointorigin" + }, + pgfpointpolar = { + arguments = { + {meta = "degree"}, + {literal = "{"}, + {meta = "radius"}, + {literal = "/"}, + {meta = "y-radius"}, + {literal = "}"} + }, + details = [[ +Yields a point location given in polar coordinates. You can specify the +angle only in degrees, radians are not supported, currently. + +If the optional ⟨y-radius⟩ is given, the polar coordinate is actually a +coordinate on an ellipse whose $x$-radius is given by ⟨radius⟩ and whose +$y$-radius is given by ⟨y-radius⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \foreach \angle in {0,10,...,90} + {\pgfpathcircle{\pgfpointpolar{\angle}{1cm}}{2pt}} + \pgfusepath{fill} + \end{tikzpicture} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \foreach \angle in {0,10,...,90} + {\pgfpathcircle{\pgfpointpolar{\angle}{1cm and 2cm}}{2pt}} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointpolar" + }, + pgfpointpolarxy = { + arguments = { + {meta = "degree"}, + {literal = "{"}, + {meta = "radius"}, + {literal = "/"}, + {meta = "y-radius"}, + {literal = "}"} + }, + details = [[ +This command is similar to the `\pgfpointpolar` command, but the +⟨radius⟩ is now a factor to be interpreted in the $xy$-coordinate +system. This means that a degree of `0` is the same as the $x$-vector of +the $xy$-coordinate system times ⟨radius⟩ and a degree of `90` is the +$y$-vector times ⟨radius⟩. As for `\pgfpointpolar`, a ⟨radius⟩ can also +be a pair separated by a slash. In this case, the $x$- and $y$-vectors +are multiplied by different factors. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \begin{scope}[x={(1cm,-5mm)},y=1.5cm] + \foreach \angle in {0,10,...,90} + {\pgfpathcircle{\pgfpointpolarxy{\angle}{1}}{2pt}} + \pgfusepath{fill} + \end{scope} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointpolarxy" + }, + pgfpointscale = { + arguments = {{meta = "factor"}, {meta = "coordinate"}}, + details = [[ +Returns the vector $⟨factor⟩⟨coordinate⟩$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpointscale{1.5}{\pgfpoint{1cm}{0cm}}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointscale" + }, + pgfpointshapeborder = { + arguments = {{meta = "node"}, {meta = "point"}}, + details = [[ +This command returns the point on the border of the shape that lies on a +straight line from the center of the node to ⟨point⟩. For complex shapes +it is not guaranteed that this point will actually lie on the border, it +may be on the border of a "simplified" version of the shape. + + \begin{pgfpicture} + \begin{pgfscope} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + \end{pgfscope} + \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{2cm}{1cm}}}{2pt} + \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt} + \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{-1cm}{1cm}}}{2pt} + \pgfpathcircle{\pgfpoint{-1cm}{1cm}}{2pt} + \pgfusepath{fill} + \end{pgfpicture} + +*Remark:* If the given ⟨point⟩ is almost identical to the center of +⟨node⟩, the node center is returned and a warning message will be +printed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointshapeborder" + }, + pgfpointspherical = { + arguments = {{meta = "longitude"}, {meta = "latitude"}, {meta = "radius"}}, + details = [[ +This command yields a point "on the surface of the earth" specified by +the ⟨longitude⟩ and the ⟨latitude⟩. The radius of the earth is given by +⟨radius⟩. The equator lies in the $xy$-plane. + + \begin{tikzpicture} + \pgfsetfillcolor{lightgray} + + \foreach \latitude in {-90,-75,...,30} + { + \foreach \longitude in {0,20,...,360} + { + \pgfpathmoveto{\pgfpointspherical{\longitude}{\latitude}{1}} + \pgfpathlineto{\pgfpointspherical{\longitude+20}{\latitude}{1}} + \pgfpathlineto{\pgfpointspherical{\longitude+20}{\latitude+15}{1}} + \pgfpathlineto{\pgfpointspherical{\longitude}{\latitude+15}{1}} + \pgfpathclose + } + \pgfusepath{fill,stroke} + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointspherical" + }, + pgfpointtransformed = { + arguments = {{meta = "point"}}, + details = [[ +Applies current transformation matrix to `{point}` $(x,y)$ and returns a +transformed point $(ax+cy+s,bx+dy+t)$. Normally, this is done +automatically by commands like `\pgfpathlineto` or `\pgfpathmoveto`, but +sometimes you may wish to access a transformed point yourself. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointtransformed" + }, + pgfpointtransformednonlinear = { + arguments = {{meta = "point"}}, + details = [[ +Works like `\pgfpointtransformed`, but also applies the current +nonlinear transformation; that is, it first applies the current linear +transformation and then the current nonlinear transformations. Note +that, just like `\pgfpointtransformed`, you normally do not call this +function directly since it is called internally by the path drawing +commands. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointtransformednonlinear" + }, + pgfpointxy = { + arguments = {{meta = "$s_x$"}, {meta = "$s_y$"}}, + details = [[ +Yields a point that is situated at $s_x$ times the $x$-vector plus $s_y$ +times the $y$-vector. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointxy" + }, + pgfpointxyz = { + arguments = {{meta = "$s_x$"}, {meta = "$s_y$"}, {meta = "$s_z$"}}, + details = [[ +Yields a point that is situated at $s_x$ times the $x$-vector plus $s_y$ +times the $y$-vector plus $s_z$ times the $z$-vector. + + \begin{pgfpicture} + \pgfsetarrowsend{to} + + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{0}{0}{1}} + \pgfusepath{stroke} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{0}{1}{0}} + \pgfusepath{stroke} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{1}{0}{0}} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointxyz" + }, + pgfpoptype = { + details = [[ +Restores the most recent type from the internal global stack of types. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpoptype" + }, + pgfpositionnodelater = { + arguments = {{meta = "macro name"}}, + details = [[ +This command is not a replacement for `\pgfnode`. Rather, when this +command is used in a scope, all subsequent node creations in this scope +will be affected in the following way: When a node is created, it is not +inserted into the current picture. Instead, it is stored in the box +`\pgfpositionnodelaterbox`. Furthermore, the node is not relevant for +the picture's bounding box, but a bounding box for the node is computed +and stored in the macros `\pgfpositionnodelaterminx` to +`\pgfpositionnodelatermaxy`. Then, the ⟨macro name⟩ is called with the +following macros set up: + +Once a late node has been created, you can add arbitrary code in the +same picture. Then, at some later point, you call `\pgfpositionnodenow` +to finally position the node at a given position. At this point, the +above macros must have the exact same values they had when ⟨macro name⟩ +was called. Note that the above macros are local to a scope that ends +right after the call to ⟨macro name⟩, so it is your job to copy the +values to safety inside ⟨macro name⟩. + +The following two macros will also be set inside the call to ⟨macro +name⟩, but they are only "informative" in the sense that you need *not* +restore these macros when `\pgfpositionnodenow` is called. + +By setting ⟨macro name⟩ to `\relax` (which is the default), you can +switch off the whole mechanism. When a picture is interrupted, this is +done automatically. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelater" + }, + pgfpositionnodelaterbox = { + details = [[ +A box register number (`0` currently) that stores the node's paths and +texts. You should move the contents of this box to a box of your choice +inside ⟨macro name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelaterbox" + }, + pgfpositionnodelatermaxx = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelatermaxx" + }, + pgfpositionnodelatermaxy = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelatermaxy" + }, + pgfpositionnodelaterminx = { + details = [[ +The minimal $x$-position of a bounding box of the node. This bounding +box refers to the node when it is positioned with the anchor at the +origin. It is guaranteed, that this macro will contain a dimension in +the format ⟨number⟩`pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelaterminx" + }, + pgfpositionnodelaterminy = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelaterminy" + }, + pgfpositionnodelatername = { + details = [[ +The name of the just-created-node. This name will be the originally +"desired" name of the box plus the fixed prefix +`not yet positionedPGFINTERNAL`. The idea is to ensure that the original +name is not inadvertently used before the node is actually positioned. +When `\pgfpositionnodenow` is called, it will change the name to the +original name. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelatername" + }, + pgfpositionnodelaterpath = { + details = [[ +This macro stores the path of the background of the node. See Section ?? +for an overview of how these paths are encode. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelaterpath" + }, + pgfpositionnodenow = { + arguments = {{meta = "coordinate"}}, + details = [[ +This command is used to position a node that has previously been created +using the command `\pgfpositionnodelater`. When `\pgfpositionnodenow` is +called, the macros and boxes mentioned in the description of +`\pgfpositionnodenow` must be set to the value they had when the ⟨macro +name⟩ was called. Provided this is the case, this command will insert +the box into the current picture, shifted by ⟨coordinate⟩. Then, the +late code (see below) is called. Subsequently, you can refer to the node +with its original name as if it had just been created. + + \newbox\mybox + + \def\mysaver{ + \global\setbox\mybox=\box\pgfpositionnodelaterbox + \global\let\myname=\pgfpositionnodelatername + \global\let\myminx=\pgfpositionnodelaterminx + \global\let\myminy=\pgfpositionnodelaterminy + \global\let\mymaxx=\pgfpositionnodelatermaxx + \global\let\mymaxy=\pgfpositionnodelatermaxy + } + + \begin{tikzpicture} + { + \pgfpositionnodelater{\mysaver} + \node [fill=blue!20,below,rotate=30] (hi) {Hello world}; + } + \draw [help lines] (0,0) grid (3,2); + + \let\pgfpositionnodelatername=\myname + \let\pgfpositionnodelaterminx=\myminx + \let\pgfpositionnodelaterminy=\myminy + \let\pgfpositionnodelatermaxx=\mymaxx + \let\pgfpositionnodelatermaxy=\mymaxy + \setbox\pgfpositionnodelaterbox=\box\mybox + \pgfpositionnodenow{\pgfqpoint{2cm}{2cm}} + + \draw (hi) -- (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodenow" + }, + pgfprofileend = { + arguments = {{meta = "profiler entry name"}}, + details = [[ +Stops (or interrupts) timing of ⟨profiler entry name⟩. + +This command finishes a preceding call to `\pgfprofilestart`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofileend" + }, + pgfprofileifisrunning = { + arguments = { + {meta = "profiler entry name"}, + {meta = "true code"}, + {meta = "false code"} + }, + details = [[ +Invokes `{true code}` if `{profiler entry name}` is currently running +and `{false code}` otherwise. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofileifisrunning" + }, + pgfprofilenew = { + arguments = {{meta = "name"}}, + details = [[ +Defines a new profiler entry named ⟨name⟩. + +This updates a set of internal registers used to track the profiler +entry. The ⟨name⟩ can be arbitrary, it doesn't need to be related to any +TeX macro. + +The actual job of counting seconds is accomplished using +`\pgfprofilestart``{name}` followed eventually by the command +`\pgfprofileend``{name}`. + +It doesn't hurt if `\pgfprofilenew` is called multiple times with the +same name. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilenew" + }, + pgfprofilenewforcommand = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "profiler entry name", + optional = true + }, + {meta = "\\textbackslash macro"}, + {meta = "arguments"} + }, + details = [[ +Defines a new profiler entry which will measure the time spent in +⟨\\macro⟩. This calls `\pgfprofilenew` and replaces the current +definition of ⟨\\macro⟩ with a new one. + +If `[profiler entry name]` has been provided, this defines the argument +for `\pgfprofilenew`. It is allowed to use the same name for multiple +commands; in this case, they are treated as if it where the same +command. If the optional argument is not used, the profiler entry will +be called '`\pgfprofilecs`⟨macro⟩' (⟨macro⟩ without backslash) where +`\pgfprofilecs` is predefined to be `<CS>`. + +The replacement macro will collect all required arguments, start +counting, invoke the original macro definition and stop counting. + +The following macro types are supported within +`\pgfprofilenewforcommand`: + +- commands which take one (optional) argument in square brackets + followed by one optional argument which has to be delimited by curly + braces (use an empty argument for ⟨arguments⟩ in this case), + +- commands which take one (optional) argument in square brackets and + *exactly* ⟨arguments⟩ arguments afterwards. + +Take a look at `\pgfprofilenewforcommandpattern` in case you have more +complicated commands. + +Note that the library can't detect if a command has been redefined +somewhere. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilenewforcommand" + }, + pgfprofilenewforcommandpattern = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "profiler entry name", + optional = true + }, + {meta = "\\textbackslash macro"}, + {meta = "argument pattern"}, + {meta = "invocation pattern"} + }, + details = [[ +A variant of `\pgfprofilenewforcommand` which can be used with arbitrary +⟨argument patterns⟩. Example: + + \def\mymacro#1\to#2\in#3{ ... } + \pgfprofilenewforcommandpattern{\mymacro}{#1\to#2\in#3}{{#1}\to{#2}\in{#3}} + +Note that `\pgfprofilenewforcommand` is a special case of +`\pgfprofilenewforcommandpattern`: + + \def\mymacro#1#2{ ... } + \pgfprofilenewforcommand\macro{2} + \pgfprofilenewforcommandpattern{\mymacro}{#1#2}{{#1}{#2}} + +Thus, ⟨argument pattern⟩ is a copy-paste from the definition of your +command. The ⟨invocation pattern⟩ is used by the `profiler` library to +invoke the *original* command, so it is closely related to ⟨argument +pattern⟩, but it needs extra curly braces around each argument. + +The behavior of `\pgfprofilenewforcommandpattern` is the same as +discussed above: it defines a new profiler entry which will measure the +time spent in ⟨\\macro⟩. The details about this definition has already +been described. Note that up to one optional argument in square brackets +is also checked automatically. + +If you like to profile a command which doesn't match here for whatever +reasons, you'll have to redefine it manually and insert +`\pgfprofilestart` and `\pgfprofileend` in appropriate places. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilenewforcommandpattern" + }, + pgfprofilenewforenvironment = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "profiler entry name", + optional = true + }, + {meta = "environment name"} + }, + details = [[ +Defines a new profiler entry which measures time spent in the +environment ⟨environment name⟩. + +This calls `\pgfprofilenew` and handles the begin/end of the environment +automatically. + +The argument for `\pgfprofilenew` is ⟨profiler entry name⟩, or, if this +optional argument is not used, it is '`\pgfprofileenv`⟨environment +name⟩' where `\pgfprofileenv` is predefined as `<ENV>`. Again, it is +permitted to use the same ⟨profiler entry name⟩ multiple times to merge +different commands into one output section. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilenewforenvironment" + }, + pgfprofilepostprocess = { + details = [[ +For LaTeX, this command is installed automatically in `\end{document}`. +It stops all running timings, evaluates them and returns the result into +the logfile. Furthermore, it generates a text table called +`\jobname.profiler.`⟨YYYY⟩`-`⟨MM⟩`-`⟨DD⟩`_ `⟨HH⟩`h_ `⟨MM⟩`m.dat` with +the same information. + +Note that the `profiler` library predefines two profiler entries, namely +`main job` which counts time from the beginning of the document until +`\pgfprofilepostprocess` and `preamble` which counts time from the +beginning of the document until `\begin{document}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilepostprocess" + }, + pgfprofilesetrel = { + arguments = {{meta = "profiler entry name"}}, + details = [[ +Sets the profiler entry whose total time will be used to compute all +other relative times. Thus, ⟨profiler entry name⟩ will use $100\%$ of +the total time per definition, all other relative times are relative to +this one. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilesetrel" + }, + pgfprofileshowinvocationsexpandedfor = { + arguments = {{meta = "profiler entry name"}}, + details = [[ +A variant of `\pgfprofileshowinvocationsfor` which will expand all +arguments for ⟨profiler entry name⟩ before showing them. The invocation +as such is not affected by this expansion. + +This expansion (with `\edef`) might yield unrecoverable errors for some +commands. Handle with care. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofileshowinvocationsexpandedfor" + }, + pgfprofileshowinvocationsfor = { + arguments = {{meta = "profiler entry name"}}, + details = [[ +Enables verbose output for *every* invocation of ⟨profiler entry name⟩. + +This is only available for profiler entries for commands (those created +by `\pgfprofilenewforcommand` for example). It will also show all given +arguments. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofileshowinvocationsfor" + }, + pgfprofilestart = { + arguments = {{meta = "profiler entry name"}}, + details = [[ +Starts (or resumes) timing of ⟨profiler entry name⟩. The argument must +have been declared in the preamble using `\pgfprofilenew`. + +Nested calls of `\pgfprofilestart` with the same argument will be +ignored. + +The invocation of this command doesn't change the environment: it +doesn't introduce any TeX groups nor does it modify the token list. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilestart" + }, + pgfpushtype = { + details = [[ +Pushes the current type on an internal global stack. The idea is to +allow you to temporarily change the current type without having to open +a TeX scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpushtype" + }, + pgfqbox = { + arguments = {{meta = "box number"}}, + details = [[ +This command inserts a TeX box into a `{pgfpicture}` by "escaping" to +TeX, inserting the box number ⟨box number⟩ at the origin, and then +returning to the typesetting the picture. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqbox" + }, + pgfqboxsynced = { + arguments = {{meta = "box number"}}, + details = [[ +This command works similarly to the `\pgfqbox` command. However, before +inserting the text in ⟨box number⟩, the current coordinate +transformation matrix is applied to the current canvas transformation +matrix (is it "synced" with this matrix, hence the name). + +Thus, this command basically has the same effect as if you first called +`\pgflowlevelsynccm` followed by `\pgfqbox`. However, this command will +use `\hskip` and `\raise` commands for the "translational part" of the +coordinate transformation matrix, instead of adding the translational +part to the current canvas transformation matrix directly. Both methods +have the same effect (box ⟨box number⟩ is translated to where it should +be), but the method used by `\pgfqboxsynced` ensures that hyperlinks are +placed correctly. Note that scaling and rotation will not (cannot, even) +apply to hyperlinks. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqboxsynced" + }, + pgfqkeys = { + arguments = {{meta = "default path"}, {meta = "key list"}}, + details = [[ +This command has the same effect as `\pgfkeys{`⟨default path⟩`/.cd,`⟨key +list⟩`}`, it is only marginally quicker. This command should not be used +in user code, but rather in commands like `\tikzset` or `\pgfset` that +get called very often. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqkeys" + }, + pgfqkeysactivatefamiliesandfilteroptions = { + arguments = { + {meta = "family list"}, + {meta = "default path"}, + {meta = "key--value-list"} + }, + details = [[ +The 'quick' default path variant of +`\pgfkeysactivatefamiliesandfilteroptions`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqkeysactivatefamiliesandfilteroptions" + }, + pgfqkeysactivatesinglefamilyandfilteroptions = { + arguments = { + {meta = "family name"}, + {meta = "default path"}, + {meta = "key--value-list"} + }, + details = [[ +The 'quick' default path variant of +`\pgfkeysactivatesinglefamilyandfilteroptions`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqkeysactivatesinglefamilyandfilteroptions" + }, + pgfqkeysalso = { + arguments = {{meta = "default path"}, {meta = "key list"}}, + details = [[ +This command has the same effect as `\pgfkeysalso{`⟨default +path⟩`/.cd,`⟨key list⟩`}`, it is only quicker. Changing the default path +inside a `\pgfkeyalso` is dangerous, so use with care. A rather safe +place to call this command is at the beginning of a TeX group. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqkeysalso" + }, + pgfqkeysfiltered = { + arguments = {{meta = "default-path"}, {meta = "key--value-list"}}, + details = [[ +A variant of `\pgfkeysfiltered` which uses the 'quick' search path +setting. It is the `\pgfqkeys` variant of `\pgfkeysfiltered`, see the +documentation for `\pgfqkeys` for more details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqkeysfiltered" + }, + pgfqpoint = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +This command does the same as `\pgfpoint`, but ⟨x⟩ and ⟨y⟩ must be +simple dimensions like `1pt` or `1cm`. Things like `2ex` or `2cm+1pt` +are not allowed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqpoint" + }, + pgfqpointscale = { + arguments = {{meta = "factor"}, {meta = "coordinate"}}, + details = [[ +As `\pgfpointscale`, but `{factor}` must be a simple number without +unit, as for the other "quick" commands. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqpointscale" + }, + pgfqpointxy = { + arguments = {{meta = "$s_x$"}, {meta = "$s_y$"}}, + details = [[ +This command does the same as `\pgfpointxy`, but ⟨$s_x$⟩ and ⟨$s_y$⟩ +must be simple numbers without unit, like `1.234` or `5.0`. Mathematical +expressions or units are not allowed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqpointxy" + }, + pgfqpointxyz = { + arguments = {{meta = "$s_x$"}, {meta = "$s_y$"}, {meta = "$s_z$"}}, + details = [[ +As `\pgfqpointxy`, but for three-dimensional coordinates. Any argument +needs to be a number without unit. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqpointxyz" + }, + pgfrdfabout = { + arguments = {{meta = "text"}}, + details = [[ +Adds the RDF attribute `about="`⟨text⟩`"` to the next id scope (please +see the RDFa specification for details on the semantics of `about` in +the context of the resource description framework). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfabout" + }, + pgfrdfcontent = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfcontent" + }, + pgfrdfdatatype = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfdatatype" + }, + pgfrdfhref = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfhref" + }, + pgfrdfinlist = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfinlist" + }, + pgfrdfprefix = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfprefix" + }, + pgfrdfproperty = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfproperty" + }, + pgfrdfrel = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfrel" + }, + pgfrdfresource = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfresource" + }, + pgfrdfrev = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfrev" + }, + pgfrdfsrc = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfsrc" + }, + pgfrdftypeof = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdftypeof" + }, + pgfrdfvocab = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfvocab" + }, + pgfrealjobname = { + arguments = {{meta = "name"}}, + details = [[ +Tells PGF the real name of your job. For instance, if you have a file +called `survey.tex` that contains two graphics that you wish to be +called `survey-graphic1` and `survey-graphic2`, then you should write +the following. + + % This is file survey.tex + \documentclass{article} + ... + \usepackage{tikz} + \pgfrealjobname{survey} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrealjobname" + }, + pgfresetboundingbox = { + details = [[ +Resets the picture's bounding box. The picture will simply forget any +previous bounding box updates and start collecting from scratch. + +You can use this together with `\pgfusepath{use as bounding box}` to +replace the bounding box by the one of a particular path (ignoring +subsequent paths). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfresetboundingbox" + }, + pgfsetadditionalshadetransform = { + arguments = {{meta = "transformation"}}, + details = [[ +This command allows you to specify an additional transformation that +should be applied to shadings when the `\pgfshadepath` command is used. +The ⟨transformation⟩ should be transformation code like +`\pgftransformrotate{20}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetadditionalshadetransform" + }, + pgfsetarrows = { + arguments = {{meta = "argument"}}, + details = [[ +The ⟨argument⟩ can be of the form ⟨start arrow tip specification⟩`-`⟨end +arrow tip specification⟩. In this case, both the start and the end arrow +specification are set: + + \begin{pgfpicture} + \pgfsetarrows{Latex[length=10pt]->>} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \end{pgfpicture} + +Alternatively, ⟨argument⟩ can be of the form `[`⟨arrow keys⟩`]`. In this +case, the ⟨arrow keys⟩ will be set for all arrow tips in the current +scope, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetarrows" + }, + pgfsetarrowsend = { + arguments = {{meta = "end arrow tip specification"}}, + details = [[ +Sets the arrow tip kind used at the end of a path. + + \begin{pgfpicture} + \pgfsetarrowsstart{Latex[length=10pt]} + \pgfsetarrowsend{Computer Modern Rightarrow} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetarrowsend" + }, + pgfsetarrowsstart = { + arguments = {{meta = "start arrow tip specification"}}, + details = [[ +Sets the arrow tip kind used at the start of a (possibly curved) path. +The syntax of the ⟨start arrow specification⟩ is detailed in Section ??. + +To "clear" the start arrow, say `\pgfsetarrowsstart{}`. + + \begin{pgfpicture} + \pgfsetarrowsstart{Latex[length=10pt]} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \pgfsetarrowsstart{Computer Modern Rightarrow} + \pgfpathmoveto{\pgfpoint{0cm}{2mm}} + \pgfpathlineto{\pgfpoint{1cm}{2mm}} + \pgfusepath{stroke} + \end{pgfpicture} + +The effect of this command persists only till the end of the current +TeX scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetarrowsstart" + }, + pgfsetbaseline = { + arguments = {{meta = "dimension"}}, + details = [[ +This command specifies a $y$-coordinate of the picture that should be +used as the baseline of the whole picture. When a PGF picture has been +typeset completely, PGF must decide at which height the baseline of the +picture should lie. Normally, the baseline is set to the $y$-coordinate +of the bottom of the picture, but it is often desirable to use a +different height. + + Text + \begin{pgfpicture} + \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke} + \end{pgfpicture}, + \begin{pgfpicture} + \pgfsetbaseline{0pt} + \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke} + \end{pgfpicture}, + \begin{pgfpicture} + \pgfsetbaseline{.5ex} + \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke} + \end{pgfpicture}, + \begin{pgfpicture} + \pgfsetbaseline{-1ex} + \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke} + \end{pgfpicture}. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetbaseline" + }, + pgfsetbaselinepointlater = { + arguments = {{meta = "point"}}, + details = [[ +This command also specifies the baseline indirectly, but the +$y$-coordinate of the given ⟨point⟩ is only computed at the end of the +picture. + + Hello + \begin{pgfpicture} + \pgfsetbaselinepointlater{\pgfpointanchor{X}{base}} + % Note: no shape X, yet + \pgfnode{cross out}{center}{world.}{X}{\pgfusepath{stroke}} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetbaselinepointlater" + }, + pgfsetbaselinepointnow = { + arguments = {{meta = "point"}}, + details = [[ +This command specifies the baseline indirectly, namely as the +$y$-coordinate that the given ⟨point⟩ has when the command is called. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetbaselinepointnow" + }, + pgfsetbeveljoin = { + details = [[ +Sets the line join to a bevel join. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetbeveljoin" + }, + pgfsetblendmode = { + arguments = {{meta = "mode"}}, + details = [[ +Sets the blend mode to one of the values described in Section ??. As +described there, blend modes are an advanced feature of PDF and not +always rendered correctly. + + \tikz [transparency group] { + \pgfsetblendmode{screen} + + \fill[red!90!black] ( 90:.6) circle (1); + \fill[green!80!black] (210:.6) circle (1); + \fill[blue!90!black] (330:.6) circle (1); + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetblendmode" + }, + pgfsetbuttcap = { + details = [[ +Sets the line cap to a butt cap. See Section ?? for an explanation of +what this is. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetbuttcap" + }, + pgfsetcolor = { + arguments = {{meta = "color"}}, + details = [[ +Sets both the stroke and fill color. The difference to the normal +`\color` command is that the effect lasts till the end of the current +`{pgfscope}`, not only till the end of the current TeX group. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetcolor" + }, + pgfsetcornersarced = { + arguments = {{meta = "point"}}, + details = [[ +This command causes all subsequent corners to be replaced by little +arcs. The effect of this command lasts till the end of the current +TeX scope. + +The ⟨point⟩ dictates how large the corner arc will be. Consider a corner +made by two lines $l$ and $r$ and assume that the line $l$ comes first +on the path. The $x$-dimension of the ⟨point⟩ decides by how much the +line $l$ will be shortened, the $y$-dimension of ⟨point⟩ decides by how +much the line $r$ will be shortened. Then, the shortened lines are +connected by an arc. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \pgfsetcornersarced{\pgfpoint{5mm}{5mm}} + \pgfpathrectanglecorners{\pgfpointorigin}{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} + \end{tikzpicture} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \pgfsetcornersarced{\pgfpoint{10mm}{5mm}} + % 10mm entering, + % 5mm leaving. + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{0cm}{2cm}} + \pgfpathlineto{\pgfpoint{3cm}{2cm}} + \pgfpathcurveto + {\pgfpoint{3cm}{0cm}} + {\pgfpoint{2cm}{0cm}} + {\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \end{tikzpicture} + +If the $x$- and $y$-coordinates of ⟨point⟩ are the same and the corner +is a right angle, you will get a perfect quarter circle (well, not quite +perfect, but perfect up to six decimals). When the angle is not +$90^\circ$, you only get a fair approximation. + +More or less "all" corners will be rounded, even the corner generated by +a `\pgfpathclose` command. (The author is a bit proud of this feature.) + + \begin{pgfpicture} + \pgfsetcornersarced{\pgfpoint{4pt}{4pt}} + \pgfpathmoveto{\pgfpointpolar{0}{1cm}} + \pgfpathlineto{\pgfpointpolar{72}{1cm}} + \pgfpathlineto{\pgfpointpolar{144}{1cm}} + \pgfpathlineto{\pgfpointpolar{216}{1cm}} + \pgfpathlineto{\pgfpointpolar{288}{1cm}} + \pgfpathclose + \pgfusepath{stroke} + \end{pgfpicture} + +To return to normal (unrounded) corners, use +`\pgfsetcornersarced{\pgfpointorigin}`. + +Note that the rounding will produce strange and undesirable effects if +the lines at the corners are too short. In this case the shortening may +cause the lines to "suddenly extend over the other end" which is rarely +desirable. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetcornersarced" + }, + pgfsetcurvilinearbeziercurve = { + arguments = { + {meta = "start"}, + {meta = "first support"}, + {meta = "second support"}, + {meta = "end"} + }, + details = [[ +Prior to using any other command from this library, you first call this +function to "install" a Bézier curve to which the commands will refer. +This curve will be local to the current TeX scope and you can install +only one curve at a time. + +The main job of this command is to store the passed points internally +and to build a lookup table for distance-to-time conversions, see the +next command. + + \pgfsetcurvilinearbeziercurve + {\pgfpointorigin} + {\pgfpoint{1cm}{1cm}} + {\pgfpoint{2cm}{1cm}} + {\pgfpoint{3cm}{0cm}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetcurvilinearbeziercurve" + }, + pgfsetdash = { + arguments = {{meta = "list of even length of dimensions"}, {meta = "phase"}}, + details = [[ +Sets the dashing of a line. The first entry in the list specifies the +length of the first solid part of the list. The second entry specifies +the length of the following gap. Then comes the length of the second +solid part, following by the length of the second gap, and so on. The +⟨phase⟩ specifies where the first solid part starts relative to the +beginning of the line. + + \begin{pgfpicture} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0cm} + \pgfpathmoveto{\pgfpoint{0mm}{0mm}} + \pgfpathlineto{\pgfpoint{2cm}{0mm}} + \pgfusepath{stroke} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.1cm} + \pgfpathmoveto{\pgfpoint{0mm}{1mm}} + \pgfpathlineto{\pgfpoint{2cm}{1mm}} + \pgfusepath{stroke} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.2cm} + \pgfpathmoveto{\pgfpoint{0mm}{2mm}} + \pgfpathlineto{\pgfpoint{2cm}{2mm}} + \pgfusepath{stroke} + \end{pgfpicture} + +Use `\pgfsetdash{}{0pt}` to get a solid dashing. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetdash" + }, + pgfsetdecorationsegmenttransformation = { + arguments = {{meta = "code"}}, + details = [[ +The ⟨code⟩ will be executed at the very beginning of each segment. Note +when applying multiple decorations, this will be reset between +decorations, so it needs to be specified for each segment. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \begin{pgfdecoration}{ + {curveto}{\pgfdecoratedpathlength/3}, + {zigzag}{\pgfdecoratedpathlength/3} + { + \pgfdecorationsegmentlength=5pt + \pgfsetdecorationsegmenttransformation{\pgftransformyshift{.5cm}} + }, + {curveto}{\pgfdecoratedremainingdistance} + } + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}} + \end{pgfdecoration} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetdecorationsegmenttransformation" + }, + pgfseteorule = { + details = [[ +Dictates that the even-odd rule is used in subsequent fillings in the +current *TeX scope*. Thus, for once, the effect of this command does not +persist past the current TeX scope. + + \begin{pgfpicture} + \pgfseteorule + \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} + \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} + \pgfusepath{fill} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfseteorule" + }, + pgfsetfading = { + arguments = {{meta = "name"}, {meta = "transformations"}}, + details = [[ +This command sets the graphic state parameter "fading" to a previously +defined fading ⟨name⟩. This graphic state works like other graphic +states, that is, is persists till the end of the current scope or until +a different transparency setting is chosen. + +When the fading is installed, it will be centered on the origin with its +natural size. Anything outside the fading picture's original bounding +box will be transparent and, thus, the fading effectively clips against +this bounding box. + +The ⟨transformations⟩ are applied to the fading before it is used. They +contain normal PGF transformation commands like `\pgftransformshift`. +You can also scale the fading using this command. Note, however, that +the transformation needs to be inverted internally, which may result in +inaccuracies and the following graphics may be slightly distorted if you +use a strong ⟨transformation⟩. + + \pgfdeclarefading{fading2} + {\tikz \shade[left color=pgftransparent!0, + right color=pgftransparent!100] (0,0) rectangle (2,2);} + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + \pgfsetfading{fading2}{} + \fill [red] (0,0) rectangle (2,2); + \end{tikzpicture} + + (0,0) rectangle (2,2);}}] + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}} + \pgftransformrotate{20}} + \fill [red] (0,0) rectangle (2,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfading" + }, + pgfsetfadingforcurrentpath = { + arguments = {{meta = "name"}, {meta = "transformations"}}, + details = [[ +This command works like `\pgfsetfading`, but the fading is scaled and +transformed according to the following rules: + +1. If the current path is empty, the command has the same effect as + `\pgfsetfading`. + +2. Otherwise it is assumed that the fading has a size of 100bp times + 100bp. + +3. The fading is resized and shifted (using appropriate + transformations) such that the position + $(25\mathrm{bp},25\mathrm{bp})$ lies at the lower-left corner of the + current path and the position $(75\mathrm{bp},75\mathrm{bp})$ lies + at the upper-right corner of the current path. + +Note that these rules are the same as the ones used in `\pgfshadepath` +for shadings. After these transformations, the ⟨transformations⟩ are +executed (typically a rotation). + + \pgfdeclarehorizontalshading{shading}{100bp} + { color(0pt)=(transparent!0); color(25bp)=(transparent!0); + color(75bp)=(transparent!100); color(100bp)=(transparent!100)} + + \pgfdeclarefading{fading}{\pgfuseshading{shading}} + + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgfsetfadingforcurrentpath{fading}{} + \pgfusepath{discard} + + \fill [red] (0,0) rectangle (2,1); + + \pgfpathrectangle{\pgfpoint{0cm}{1cm}}{\pgfpoint{2cm}{1cm}} + \pgfsetfadingforcurrentpath{fading}{\pgftransformrotate{90}} + \pgfusepath{discard} + + \fill [red] (0,1) rectangle (2,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfadingforcurrentpath" + }, + pgfsetfadingforcurrentpathstroked = { + arguments = {{meta = "name"}, {meta = "transformations"}}, + details = [[ +This command works like `\pgfsetfadingforcurrentpath`, only the current +path is enlarged by the line width in both $x$- and $y$-direction. This +is exactly the enlargement necessary to compensate for the fact that if +the current path will be stroked, this much needs to be added around the +path's bounding box to actually contain the path. + + \begin{tikzpicture} + \pgfsetlinewidth{2mm} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{2cm}{0cm}} + \pgfsetfadingforcurrentpathstroked{fading}{} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfadingforcurrentpathstroked" + }, + pgfsetfillcolor = { + arguments = {{meta = "color"}}, + details = [[ +Sets the color used for filling paths to ⟨color⟩. Like the stroke color, +the effect lasts only till the next use of `\color`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfillcolor" + }, + pgfsetfillopacity = { + arguments = {{meta = "value"}}, + details = [[ +Sets the opacity of filling operations. As for stroking, the ⟨value⟩ +should be a number between `0` and `1`. + +The "filling transparency" will also be used for text and images. + + \begin{tikzpicture} + \pgfsetfillopacity{0.5} + \fill[red] (90:1cm) circle (11mm); + \fill[green] (210:1cm) circle (11mm); + \fill[blue] (-30:1cm) circle (11mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfillopacity" + }, + pgfsetfillpattern = { + arguments = {{meta = "name"}, {meta = "color"}}, + details = [[ +This command specifies that paths that are filled should be filled with +the "color" by the pattern ⟨name⟩. For an inherently colored pattern, +the ⟨color⟩ parameter is ignored. For form-only patterns, the ⟨color⟩ +parameter specifies the color to be used for the pattern. + + \begin{tikzpicture} + \pgfsetfillpattern{stars}{red} + \filldraw (0,0) rectangle (1.5,2); + + \pgfsetfillpattern{green stars}{red} + \filldraw (1.5,0) rectangle (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfillpattern" + }, + pgfsetinnerlinewidth = { + arguments = {{meta = "dimension"}}, + details = [[ +This command sets the width of the inner line. Whenever a path is +stroked (and only then), it will be stroked normally and, afterward, it +is stroked once more with the color set to the inner line color and the +line width set to ⟨dimension⟩. + +In case arrow tips are added to a path, the path is first stroked +normally, then the inner line is stroked, and then the arrow tip is +added. In case the main path is shortened because of the added arrow +tip, this shortened path is double stroked, not the original path (which +is exactly what you want). + +When the inner line width is set to 0pt, which is the default, no inner +line is stroked at all (not even a line of width 0pt). So, in order to +"switch off" double stroking, set ⟨dimension⟩ to `0pt`. + +The setting of the inner line width is local to the current TeX group +and *not* to the current PGF scope. + +Note that inner lines will *not* be drawn for paths that are also used +for clipping. However, this may change in the future, so you should not +depend on this. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfsetlinewidth{2pt} + \pgfsetinnerlinewidth{1pt} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetinnerlinewidth" + }, + pgfsetinnerstrokecolor = { + arguments = {{meta = "color"}}, + details = [[ +This command sets the ⟨color⟩ that is to be used when the inner line is +stroked. The effect of this command is also local to the current +TeX group. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfsetlinewidth{2pt} + \pgfsetinnerlinewidth{1pt} + \pgfsetinnerstrokecolor{red!50} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetinnerstrokecolor" + }, + pgfsetlayers = { + arguments = {{meta = "layer list"}}, + details = [[ +This command tells PGF which layers will be used in pictures. They are +stacked on top of each other in the order given. The layer `main` should +always be part of the list. Here is an example: + + \pgfdeclarelayer{background} + \pgfdeclarelayer{foreground} + \pgfsetlayers{background,main,foreground} + +This command should be given either outside of any picture or "directly +inside" of a picture. Here, the "directly inside" means that there +should be no further level of TeX grouping between `\pgfsetlayers` and +the matching `\end{pgfpicture}` (no closing braces, no `\end{...}`). It +will also work if `\pgfsetlayers` is provided before `\end{tikzpicture}` +(with similar restrictions). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetlayers" + }, + pgfsetlinetofirstplotpoint = { + details = [[ +Specifies that plot handlers should issue a line-to command for the +first point of the plot. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfsetlinetofirstplotpoint + \pgfplothandlerlineto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{3cm}{2cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetlinetofirstplotpoint" + }, + pgfsetlinewidth = { + arguments = {{meta = "line width"}}, + details = [[ +This command sets the line width for subsequent strokes (in the current +`pgfscope`). The line width is given as a normal TeX dimension like +`0.4pt` or `1mm`. + + \begin{pgfpicture} + \pgfsetlinewidth{1mm} + \pgfpathmoveto{\pgfpoint{0mm}{0mm}} + \pgfpathlineto{\pgfpoint{2cm}{0mm}} + \pgfusepath{stroke} + \pgfsetlinewidth{2\pgflinewidth} % double in size + \pgfpathmoveto{\pgfpoint{0mm}{5mm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetlinewidth" + }, + pgfsetmatrixcolumnsep = { + arguments = {{meta = "sep list"}}, + details = [[ +This macro sets the default separation list for columns. The details of +the format of this list are explained in the description of the next +command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetmatrixcolumnsep" + }, + pgfsetmatrixrowsep = { + arguments = {{meta = "sep list"}}, + details = [[ +This macro sets the default separation list for rows. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetmatrixrowsep" + }, + pgfsetmiterjoin = { + details = [[ +Sets the line join to a miter join. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetmiterjoin" + }, + pgfsetmiterlimit = { + arguments = {{meta = "miter limit factor"}}, + details = [[ +Sets the miter limit to ⟨miter limit factor⟩. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetmiterlimit" + }, + pgfsetmovetofirstplotpoint = { + details = [[ +Specifies that the line-to plot handler (and also some other plot +handlers) should issue a move-to command for the first point of the plot +instead of a line-to. This will start a new part of the current path, +which is not always, but often, desirable. This is the default. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetmovetofirstplotpoint" + }, + pgfsetnonzerorule = { + details = [[ +Dictates that the nonzero winding number rule is used in subsequent +fillings in the current TeX scope. This is the default. + + \begin{pgfpicture} + \pgfsetnonzerorule + \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} + \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} + \pgfusepath{fill} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetnonzerorule" + }, + pgfsetplotmarkphase = { + arguments = {{meta = "phase"}}, + details = [[ +Sets the $p$ parameter to ⟨phase⟩, that is, the first mark to be drawn +is the $p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so on. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetplotmarkphase" + }, + pgfsetplotmarkrepeat = { + arguments = {{meta = "repeat"}}, + details = [[ +Sets the $r$ parameter to ⟨repeat⟩, that is, only every $r$th mark will +be drawn. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetplotmarkrepeat" + }, + pgfsetplotmarksize = { + arguments = {{meta = "dimension"}}, + details = [[ +This command sets the TeX dimension `\pgfplotmarksize` to ⟨dimension⟩. +This dimension is a "recommendation" for plot mark code at which size +the plot mark should be drawn; plot mark code may choose to ignore this +⟨dimension⟩ altogether. For circles, ⟨dimension⟩ should be the radius, +for other shapes it should be about half the width/height. + +The predefined plot marks all take this dimension into account. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfsetplotmarksize{1ex} + \pgfplothandlermark{\pgfuseplotmark{*}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetplotmarksize" + }, + pgfsetplottension = { + arguments = {{meta = "value"}}, + details = [[ +Sets the factor used by the curve plot handlers to determine the +distance of the control points from the points they control. The higher +the curvature of the curve points, the higher this value should be. A +value of $1$ will cause four points at quarter positions of a circle to +be connected using a circle. The default is $0.5$. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfsetplottension{0.75} + \pgfplothandlercurveto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetplottension" + }, + pgfsetrectcap = { + details = [[ +Sets the line cap to a square cap. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetrectcap" + }, + pgfsetroundcap = { + details = [[ +Sets the line cap to a round cap. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetroundcap" + }, + pgfsetroundjoin = { + details = [[ +Sets the line join to a round join. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetroundjoin" + }, + pgfsetshortenend = { + arguments = {{meta = "dimension"}}, + details = [[ +Works like `\pgfsetshortenstart`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetshortenend" + }, + pgfsetshortenstart = { + arguments = {{meta = "dimension"}}, + details = [[ +This command will shortened the start of every stroked path by the given +dimension. This shortening is done in addition to automatic shortening +done by a start arrow, but it can be used even if no start arrow is +given. + +It is usually better to use the `sep` key with arrow tips. + +This command is useful if you wish arrows or lines to "stop shortly +before" a given point. + + \begin{pgfpicture} + \pgfpathcircle{\pgfpointorigin}{5mm} + \pgfusepath{stroke} + \pgfsetarrows{Latex-} + \pgfsetshortenstart{4pt} + \pgfpathmoveto{\pgfpoint{5mm}{0cm}} % would be on the circle + \pgfpathlineto{\pgfpoint{2cm}{0cm}} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetshortenstart" + }, + pgfsetstrokecolor = { + arguments = {{meta = "color"}}, + details = [[ +Sets the color used for stroking lines to ⟨color⟩, where ⟨color⟩ is a +LaTeX color like `red` or `black!20!red`. Unlike the `\color` command, +the effect of this command lasts till the end of the current +`{pgfscope}` and not till the end of the current TeX group. + +The color used for stroking may be different from the color used for +filling. However, a `\color` command will always "immediately override" +any special settings for the stroke and fill colors. + +In plain TeX, this command will also work, but the problem of *defining* +a color arises. After all, plain TeX does not provide LaTeX colors. For +this reason, PGF implements a minimalistic "emulation" of the +`\definecolor`, `\colorlet`, and `\color` commands. Only gray-scale and +rgb colors are supported. For most cases this turns out to be enough. + + \begin{pgfpicture} + \pgfsetlinewidth{1pt} + \color{red} + \pgfpathcircle{\pgfpoint{0cm}{0cm}}{3mm} \pgfusepath{fill,stroke} + \pgfsetstrokecolor{black} + \pgfpathcircle{\pgfpoint{1cm}{0cm}}{3mm} \pgfusepath{fill,stroke} + \color{red} + \pgfpathcircle{\pgfpoint{2cm}{0cm}}{3mm} \pgfusepath{fill,stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetstrokecolor" + }, + pgfsetstrokeopacity = { + arguments = {{meta = "value"}}, + details = [[ +Sets the opacity of stroking operations. The ⟨value⟩ should be a number +between `0` and `1`, where `1` means "fully opaque" and `0` means "fully +transparent". A value like `0.5` will cause paths to be stroked in a +semitransparent way. + + \begin{pgfpicture} + \pgfsetlinewidth{5mm} + \color{red} + \pgfpathcircle{\pgfpoint{0cm}{0cm}}{10mm} \pgfusepath{stroke} + \color{black} + \pgfsetstrokeopacity{0.5} + \pgfpathcircle{\pgfpoint{1cm}{0cm}}{10mm} \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetstrokeopacity" + }, + pgfsettransform = { + arguments = {{meta = "macro"}}, + details = [[ +Reinstalls a coordinate transformation matrix that was previously saved +using `\pgfgettransform`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsettransform" + }, + pgfsettransformentries = { + arguments = { + {meta = "a"}, + {meta = "b"}, + {meta = "c"}, + {meta = "d"}, + {meta = "shiftx"}, + {meta = "shifty"} + }, + details = [[ +Reinstalls a coordinate transformation matrix that was previously saved +using the storage command `\pgfgettransformentries`. This command can +also be used to replace any previously existing coordinate +transformation matrix (it is thus equivalent to `\pgftransformreset` +followed by `\pgftransformcm`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsettransformentries" + }, + pgfsettransformnonlinearflatness = { + arguments = {{meta = "dimension"}}, + details = [[ +Whenever in a to-be-drawn curve the $L^\infty$-distance (maximum of the +distances in $x$- and $y$-directions) between the start of a curve and +its first control point or between the first and second control points +or between the second control point and the end is more than ⟨distance⟩, +the curve gets split in the middle (more precisely, at time $t= 0.5$) +and we draw the two parts individually (for them, splitting may occur +again, if the curve is still too long). + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + \draw[red] (0:20mm) arc [start angle=0, end angle=90, radius=2cm]; + { + \pgftransformnonlinear{\polartransformation} + \pgfsettransformnonlinearflatness{2pt} % very precise + \draw (0,20mm) -- (90pt,20mm); + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsettransformnonlinearflatness" + }, + pgfsetxvec = { + arguments = {{meta = "point"}}, + details = [[ +Sets that current $x$-vector for usage in the $xyz$-coordinate system. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} + + \color{red} + \pgfsetxvec{\pgfpoint{0.75cm}{0cm}} + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetxvec" + }, + pgfsetyvec = { + arguments = {{meta = "point"}}, + details = [[ +Works like `\pgfsetxvec`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetyvec" + }, + pgfsetzvec = { + arguments = {{meta = "point"}}, + details = [[ +Works like `\pgfsetxvec`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetzvec" + }, + pgfshadecolortocmyk = { + arguments = {{meta = "color name"}, {meta = "macro"}}, + details = [[ +This command takes ⟨color name⟩ as input, converts it to CMYK and stores +the color's cyan/magenta/yellow/black components real numbers between +0.0 and 1.0 separated by spaces. + +In addition, four macros suffixed with `cyan`, `magenta`, `yellow` and +`black` are defined, which store the individual components of ⟨color +name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfshadecolortocmyk" + }, + pgfshadecolortogray = { + arguments = {{meta = "color name"}, {meta = "macro"}}, + details = [[ +This command takes ⟨color name⟩ as input converts it to grayscale and +stores the color's value as a real number between 0.0 and 1.0. + +Although it's not needed, for consistency a second macro suffixed with +`gray` is also defined. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfshadecolortogray" + }, + pgfshadecolortorgb = { + arguments = {{meta = "color name"}, {meta = "macro"}}, + details = [[ +This command takes ⟨color name⟩ as input, converts it to RGB and stores +the color's red/green/blue components real numbers between 0.0 and 1.0 +separated by spaces (which is exactly what you need if you want to push +it on a stack) in ⟨macro⟩. This macro can then be used inside the ⟨type +4 function⟩ argument for `\pgfdeclarefunctionalshading`. + + \pgfdeclarefunctionalshading[mycol]{sweep}{\pgfpoint{-1cm}{-1cm}} + {\pgfpoint{1cm}{1cm}}{\pgfshadecolortorgb{mycol}{\myrgb}}{ + 2 copy % whirl + % Calculate "safe" atan of position + 2 copy abs exch abs add 0.0001 ge { atan } { pop } ifelse + 3 1 roll + dup mul exch + dup mul add sqrt + 30 mul + add + sin + 1 add 2 div + dup + \myrgb % push mycol + 5 4 roll % multiply all components by calculated value + mul + 3 1 roll + 3 index + mul + 3 1 roll + 4 3 roll + mul + 3 1 roll + } + \colorlet{mycol}{white}% + \pgfuseshading{sweep}% + \colorlet{mycol}{red}% + \pgfuseshading{sweep} + +In addition, three macros suffixed with `red`, `green` and `blue` are +defined, which store the individual components of ⟨color name⟩. These +can also be used in the ⟨type 4 function⟩ argument. + + \pgfshadecolortorgb{orange}{\mycol} + |\mycol|=\mycol |\mycolred|=\mycolred |\mycolgreen|=\mycolgreen |\mycolblue|=\mycolblue +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfshadecolortorgb" + }, + pgfshadepath = { + arguments = {{meta = "shading name"}, {meta = "angle"}}, + details = [[ +This command must be used inside a `{pgfpicture}` environment. The +effect is a bit complex, so let us go over it step by step. + +First, PGF will set up a local scope. + +Second, it uses the current path to clip everything inside this scope. +However, the current path is once more available after the scope, so it +can be used, for example, to stroke it. + +Now, the ⟨shading name⟩ should be a shading whose width and height are +100 bp, that is, 100 big points. PGF has a look at the bounding box of +the current path. This bounding box is computed automatically when a +path is computed; however, it can sometimes be (quite a bit) too large, +especially when complicated curves are involved. + +Inside the scope, the low-level transformation matrix is modified. The +center of the shading is translated (moved) such that it lies on the +center of the bounding box of the path. The low-level coordinate system +is also scaled such that the shading "covers" the path (the details are +a bit more complex, see below). Then, the coordinate system is rotated +by ⟨angle⟩. Finally, if the macro `\pgfsetadditionalshadetransform` has +been used, an additional transformation is applied. + +After everything has been set up, the shading is inserted. Due to the +transformations and clippings, the effect will be that the shading seems +to "fill" the path. + +If both the path and the shadings were always rectangles and if +rotations were never involved, it would be easy to scale shadings such +they always cover the path. However, when a vertical shading is rotated, +it must obviously be "magnified" so that it still covers the path. +Things get worse when the path is not a rectangle itself. + +For these reasons, things work slightly differently "in reality". The +shading is scaled and translated such that the point +$(50\mathrm{bp},50\mathrm{bp})$, which is the middle of the shading, is +at the middle of the path and such that the point +$(25\mathrm{bp},25\mathrm{bp})$ is at the lower left corner of the path +and that $(75\mathrm{bp},75\mathrm{bp})$ is at upper right corner. + +In other words, only the center quarter of the shading will actually +"survive the clipping" if the path is a rectangle. If the path is not a +rectangle, but, say, a circle, even less is seen of the shading. Here is +an example that demonstrates this effect: + + \pgfdeclareverticalshading{myshadingE}{100bp} + {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} + \pgfuseshading{myshadingE} + \hskip 1cm + \begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingE}{0} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{1cm}{2cm}} + \pgfshadepath{myshadingE}{0} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{5cm}{0cm}}{\pgfpoint{2cm}{2cm}} + \pgfshadepath{myshadingE}{45} + \pgfusepath{stroke} + \pgfpathcircle{\pgfpoint{9cm}{1cm}}{1cm} + \pgfshadepath{myshadingE}{45} + \pgfusepath{stroke} + \end{pgfpicture} + +As can be seen above in the last case, the "hidden" part of the shading +actually *can* become visible if the shading is rotated. The reason is +that it is scaled as if no rotation took place, then the rotation is +done. + +The following graphics show which part of the shading are actually +shown: + + \pgfdeclareverticalshading{myshadingF}{100bp} + {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} + \begin{tikzpicture} + \draw (50bp,50bp) node {\pgfuseshading{myshadingF}}; + \draw[white,thick] (25bp,25bp) rectangle (75bp,75bp); + \draw (50bp,0bp) node[below] {first two applications}; + + \begin{scope}[xshift=5cm] + \draw (50bp,50bp) node{\pgfuseshading{myshadingF}}; + \draw[rotate around={45:(50bp,50bp)},white,thick] (25bp,25bp) rectangle (75bp,75bp); + \draw (50bp,0bp) node[below] {third application}; + \end{scope} + + \begin{scope}[xshift=10cm] + \draw (50bp,50bp) node{\pgfuseshading{myshadingF}}; + \draw[white,thick] (50bp,50bp) circle (25bp); + \draw (50bp,0bp) node[below] {fourth application}; + \end{scope} + \end{tikzpicture} + +An advantage of this approach is that when you rotate a radial shading, +no distortion is introduced: + + \pgfdeclareradialshading{ballshading}{\pgfpoint{-10bp}{10bp}} + {color(0bp)=(red!15!white); color(9bp)=(red!75!white); + color(18bp)=(red!70!black); color(25bp)=(red!50!black); color(50bp)=(black)} + \pgfuseshading{ballshading} + \hskip 1cm + \begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{1cm}{1cm}} + \pgfshadepath{ballshading}{0} + \pgfusepath{} + \pgfpathcircle{\pgfpoint{3cm}{0cm}}{1cm} + \pgfshadepath{ballshading}{0} + \pgfusepath{} + \pgfpathcircle{\pgfpoint{6cm}{0cm}}{1cm} + \pgfshadepath{ballshading}{45} + \pgfusepath{} + \end{pgfpicture} + +If you specify a rotation of $90^\circ$ and if the path is not a square, +but an elongated rectangle, the "desired" effect results: The shading +will exactly vary between the colors at the 25bp and 75bp boundaries. +Here is an example: + + \pgfdeclareverticalshading{myshadingG}{100bp} + {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} + \begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingG}{0} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingG}{90} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{6cm}{0cm}}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingG}{45} + \pgfusepath{stroke} + \end{pgfpicture} + +As a final example, let us define a "rainbow spectrum" shading for use +with TikZ. + + \pgfdeclareverticalshading{rainbow}{100bp} + {color(0bp)=(red); color(25bp)=(red); color(35bp)=(yellow); + color(45bp)=(green); color(55bp)=(cyan); color(65bp)=(blue); + color(75bp)=(violet); color(100bp)=(violet)} + \begin{tikzpicture}[shading=rainbow] + \shade (0,0) rectangle node[white] {\textsc{pride}} (2,1); + \shade[shading angle=90] (3,0) rectangle +(1,2); + \end{tikzpicture} + +Note that rainbow shadings are *way* too colorful in almost all +applications. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfshadepath" + }, + pgfsnapshot = { + arguments = {{meta = "time"}}, + details = [[ +When this command is used inside a TeX scope, the behavior of +`\pgfanimateattribute` changes: Instead of adding an animation to the +object and the attribute, the object's attribute is set to value it +would have during the animation at time ⟨time⟩. Note that when this +command is used in a TeX scope, no animation is created and no support +by the driver is needed (so, it works with PDF). + + \tikz [make snapshot of=1s, + animate = { myself: = { + :rotate = { 0s = "0", 2s = "90" }, + :color = { 0s = "red", 2s = "green" }, + :line width = { 0s = "0mm", 4s = "4mm" } + }}] + \node [fill=black!20, draw] { Node }; + +**Timing and Events.** The timeline of an animation normally starts at a +"moment `0s`" and the ⟨time⟩ is considered relative to this time. For +instance, if a timeline contains, say, the settings `entry={2s}{0}` and +`entry={3s}{10}` and `{time}` is set to `2.5s`, then the value the +attribute will get is 5. + +It is, however, also possible to specify that animations begin and end +at certain times relative to events like a `click` event. *These events +are not relevant with respect to snapshots.* However, there is one key +that allows you to specify the beginning of the snapshot timeline: + +Note that the `end` keys have no effect with snapshots, that is, with a +snapshot all animations always run till the end of the timeline (which +may or may not be "forever"). + +**Limitations.** For snapshots, the value an animation has at time +⟨time⟩ must be computed by TeX. While in many cases this is easy to +achieve, in some cases this is not trivial such as a timeline for a path +with repeats plus smoothing via splines. An additional complication is +the fact that an animation may be specified at a place far removed from +the actual to-be-animated object. For these reasons, certain limitations +apply to snapshots: + +- The `begin` and `begin on` keys have no effect (but `begin snapshot` + has one. + +- The `end` and `end on` keys have no effect. + +- The `current value` may not be used in a timeline (since PGF cannot + really determine this value). + +- The `accumulating` specification may not be used with paths, views, + or motions. + +- Since the timing computations are done using TeX code, they are not + necessarily stable. For instance, when a time interval is very small + and there are many repeats or when a spline is very complicated, the + calculated values may not be fully accurate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsnapshot" + }, + pgfsnapshotafter = { + arguments = {{meta = "time"}}, + details = [[ +This command works exactly like `\pgfsnapshot` only the "moment" that +⟨time⟩ refers to is conceptually $⟨time⟩ + \epsilon$: When timeline +specifies several values for ⟨time⟩, this command will select the last +value at ⟨time⟩, while `\pgfsnapshot` will select the first value at +⟨time⟩. Similarly, when a timeline ends at ⟨time⟩, `\pgfsnapshot` will +select the last value of the timeline while `\pgfsnapshotafter` will not +apply the animation any more: + + \foreach \t in {0,1,2,3,4} { + \pgfsnapshot{\t} + \tikz :rotate = { 0s = "0", 2s = "90", 2s = "180", 4s = "270" } + \node [draw=blue, very thick] {f}; } + + \foreach \t in {0,1,2,3,4} { + \pgfsnapshotafter{\t} + \tikz :rotate = { 0s = "0", 2s = "90", 2s = "180", 4s = "270" } + \node [draw=blue, very thick] {f}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsnapshotafter" + }, + ["pgfsys@animate"] = { + arguments = {{meta = "attribute"}}, + details = [[ +The system layer animation subsystem follows the following philosophy: +An animation always concerns an *attribute* of a *graphic object*. A +*timeline* specifies how the attribute changes its value over time. +Finally, a set of *keys* configures the animation as a whole like +whether the timeline repeats or a event that triggers the start of the +animation. The four parts of an animation, namely the *attribute*, the +*graphic object*, the *timeline*, and the *keys*, are specified in +different ways: + +1. You choose the *attribute* using the system layer command + `\pgfsysanimate`. + +2. The *graphic object* whose attribute is to be animated is *always* + specified by naming the ID of the graphic object *before* this + object is created, see Section ??. (However, in the context of TikZ, + it suffices that the animation is given in the object's options + since these are executed before the actual object is created). + +3. The *timeline* is specified using the commands `\pgfsysanimkeytime`, + which specifies a time in seconds, and `\pgfsys@animation@val...`, + which specify a value at this particular time. The timeline + specifies for a sequence of times the values the attribute will have + at these times. In between these *key times,* the value is + interpolated. + +4. The *animation keys* are specified by commands starting + `\pgfsys@animation@...` and have the following effect: They set some + property (like, say, whether the animation repeats or whether its + effect is additive) to a given value *for the current TeX scope,* + but do not create any animations. Rather, when `\pgfsysanimate` is + called, a snapshot of the current values of all animation keys is + taken and added to this animation of the attribute. + + When you set an animation key to a value, this will replace the + value previously stored for the key (all keys are empty by default + at the beginning). + + Note that animation keys are local to TeX scopes, not graphics + scopes; indeed, they have little to do with the settings of the + graphics scope other than the fact that a graphic scope is also a + TeX scope and thereby influence the values of these keys. + +A typical example of how all of this works is the following: + + \pgfsysanimkeyrepeatindefinite % Both of the following animations + % repeat indefinitely + { + \pgfsysanimkeywhom{\someid}{}% The id of a later object + \pgfsysanimkeyevent{}{}{click}{0}{begin}% Begin on a click ... + \pgfsysanimkeytime{5}{1}{1}{0}{0} % Timeline starts after 5s + \pgfsysanimvalscalar{0} % With a value of 0 + \pgfsysanimkeytime{8}{1}{1}{0}{0} % Timeline ends after 8s + \pgfsysanimvalscalar{0.9} % With a value of 0.9 + \pgfsysanimate{fillopacity}% ... and the attribute is the fill opacity + } + { + \pgfsysanimkeywhom{\someid}{}% The id of a later object + \pgfsysanimkeyoffset{0}{begin}% Begin right away ... + \pgfsysanimkeytime{1}{1}{1}{0}{0} % Timeline starts after 1s + \pgfsysanimvalcurrent % With the current value + \pgfsysanimkeytime{5}{1}{1}{0}{0} % Timeline ends after 5s + \pgfsysanimvaldimension{5pt} % With a value of 5pt + \pgfsysanimate{linewidth}% ... and the attribute is the line width + } + +As a real-life example, consider the following definitions, which will +be used in many examples in the rest of this section: Both take three +parameters: The PGF/TikZ name of a to-be animated object, a type +(relevant for objects that have subtypes or parts), and some code for +triggering the actual animation. The animation will always start when +the button is clicked. The second macro sets up things in such a way +that the animation will last two seconds, while the first leaves the +timing open. + + \def\animationexample#1#2#3{ + \tikz[fill=blue!25, draw=blue, ultra thick] { + \pgfidrefnextuse{\objid}{#1} + \pgfsysanimkeywhom{\objid}{#2} + \pgfidrefnextuse{\nodeid}{node} + \pgfsysanimkeyevent{\nodeid}{}{click}{}{begin} + #3 + \node [font=\scriptsize, circle, fill, draw, align=center] + (node) {Click \\ here}; + } + } + +Now the example, where the circle will disappear, when clicked: + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalscalar{1} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalscalar{0} + \pgfsysanimate{opacity} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animate" + }, + ["pgfsys@animation@accesskey"] = { + arguments = { + {meta = "character"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ +Begin or end the animation when a certain key is pressed. Note that this +event may not be supported by some browsers for security reasons +(prevent key loggers). + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyaccesskey{s}{}{begin} + \pgfsysanimate{translate} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@accesskey" + }, + ["pgfsys@animation@accumulate"] = { + details = [[ +Specifies that each repeat of an animation works as if the last values +attained during previous repeats are added to the current value. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-5mm} + \pgfsysanimkeyaccumulate + \pgfsysanimkeyrepeatdur{5} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@accumulate" + }, + ["pgfsys@animation@base"] = { + details = [[ +This command can be used in any place where `\pgfsys@animation@time` is +usually used. The effect is that the next value does not become part of +the timeline, but will become the value used for the attribute when no +animation is active. (Normally, when the animation is not active, no +value is set at all and the value is inherited from the surrounding +scope.) +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@base" + }, + ["pgfsys@animation@canvas@transform"] = { + arguments = {{meta = "pre"}, {meta = "post"}}, + details = [[ +In order to animate the canvas, you specify that, for instance, the +canvas should be shifted over, say, one second by 2cm from left to +right. In order to specify this, you specify that an additional shift +should be added to the canvas transformation matrix that starts out as +$(0,0)$ and ends at $(2\,\mathrm{cm},0)$. However, it is not immediately +clear what "to the right" or $(2\,\mathrm{cm},0)$ actually means: +"Right" relative to the paper? "Right" relative to the coordinate system +at the point when the animation is created? "Right" relative to the +object's local coordinate system? + +Using this command you can specify the coordinate system relative to +which all canvas animations are specified. In detail, when you add an +animation $a$ of the canvas of an object foo, the following happens: + +1. We start with the canvas transformation matrix that is installed + when the object starts. More precisely, this is the canvas + transformation matrix that is in force when the command + `\pgfsys@begin@idscope` is called for the object. The canvas + transformation matrix that is in force when the animation is created + (which is typically "way before" the object is created and may even + be in a totally different graphics scope) is irrelevant for the + animation. + +2. Now, when the object is created, the code ⟨pre⟩ is executed. It + should call `\pgfsys@transformcm` at most once. This canvas + transformation is added to the object's canvas transformation. + +3. Now, the animation $a$ of the canvas is relative to the resulting + canvas transformation. That means, when the animation shifts the + object "to the right" the animation will actually be along the + current direction of "right" in the canvas transformation resulting + from the two transformations above. + +4. Finally, at the point of creation of the to-be-animation object the + code ⟨post⟩ is executed. Again, the code should call + `\pgfsys@transformcm` at most once. The resulting transformation is + also added to the object's canvas transformation, but does *not* + influence the animation. + +The net effect of the above is that, normally, you use the ⟨pre⟩ code to +setup a transformation matrix relative to which you wish to perform your +animation and, normally, you use ⟨post⟩ to undo this transformation +(using the inverted matrix) to ensure that when no animation is in +force, the object is placed at the same position as if no animation were +used. + +Let us now have a look at some examples. We use the following macro, +which takes a pre and a post code and animates a red ball over 1cm to +the right in two seconds and rotates the blue ball over 90$^\circ$ +around the origin. The ball is placed at $(1,0)$. + + \def\animationcanvasexample#1#2{% + \animationexample{ball}{}{% + \pgfsysanimkeycanvastransform{#1}{#2}% + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm}% + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{1cm}{0cm}% + \pgfsysanimate{translate} + \fill [ball color=red,name=ball] (1,0) circle [radius=3mm]; } + \animationexample{ball}{}{% + \pgfsysanimkeycanvastransform{#1}{#2}% + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalscalar{0}% + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalscalar{90}% + \pgfsysanimate{rotate} + \fill [ball color=blue,name=ball] (1,0) circle [radius=3mm]; } } + + \animationcanvasexample + {} + {} + + \animationcanvasexample + {\pgfsys@transformshift{10mm}{0mm}} + {\pgfsys@transformshift{-10mm}{0mm}} + + \animationcanvasexample + {\pgfsys@transformcm{0.5}{0.5}{-0.5}{0.5} + {0pt}{0pt}} + {} + + \animationcanvasexample + {\pgfsys@transformcm{0.5}{0.5}{-0.5}{0.5} + {0pt}{0pt}} + {\pgfsys@transformcm{1}{-1}{1}{1} + {0pt}{0pt}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@canvas@transform" + }, + ["pgfsys@animation@event"] = { + arguments = { + {meta = "id"}, + {meta = "type"}, + {meta = "event name"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ +Specifies that the animation should begin (or end) ⟨time offset⟩ many +seconds after a certain *event* has occurred. Which events are possible +depends on the specific output language, here are the events currently +supported in SVG: + +- `click` occurs when the object with the given ⟨id⟩ and ⟨type⟩ has + been clicked. + +- `focusin` and `focusout` occur when the focus enters or leaves the + object. + +- `mouseup`, `mousedown`, `mouseover`, `mousemove`, and `mouseout` + occur when the mouse is pressed up or down on the object, moved onto + the object, moved over the object, or moved off the object. + + + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyevent{\nodeid}{}{mouseup}{}{begin} + \pgfsysanimate{translate} } + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyevent{\nodeid}{}{mousedown}{}{begin} + \pgfsysanimate{translate} } + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyevent{\nodeid}{}{mouseover}{}{begin} + \pgfsysanimate{translate} } + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyevent{\nodeid}{}{mousemove}{}{begin} + \pgfsysanimate{translate} } + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyevent{\nodeid}{}{mouseout}{}{begin} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@event" + }, + ["pgfsys@animation@freezeatend"] = { + details = [[ +When an animation ends, the question is whether the "effect" of the +animation (like changing a color or translating the coordinate system) +should disappear or "remain in force". Using this key, you specify that +at the end of the animation the last value of the attributes stays in +effect. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyfreezeatend + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@freezeatend" + }, + ["pgfsys@animation@movealong"] = { + arguments = {{meta = "path"}}, + details = [[ +Defines the ⟨path⟩ along which the motion will occur. It will simply be +executed and must call `\pgfsys@lineto` and similar path-construction +commands, but should not call other commands. + + \animationexample{node}{}{ + \pgfsysanimkeymovealong{ + \pgfsyssoftpath@movetotoken{0pt}{0pt} + \pgfsyssoftpath@linetotoken{0pt}{-5mm} + \pgfsyssoftpath@curvetosupportatoken{0pt}{-1cm}% + \pgfsyssoftpath@curvetosupportbtoken{0pt}{-1cm}% + \pgfsyssoftpath@curvetotoken{-5mm}{-1cm} } + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalscalar{0} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalscalar{1} + \pgfsysanimate{motion} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@movealong" + }, + ["pgfsys@animation@noaccumulate"] = { + details = [[ +Specifies that each repeat resets the to-be-animated value. This is the +default. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-5mm} + \pgfsysanimkeynoaccumulate + \pgfsysanimkeyrepeatdur{5} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@noaccumulate" + }, + ["pgfsys@animation@norotatealong"] = { + details = [[ +Indicates that no additional rotation should be added during the +movement. This is the default. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@norotatealong" + }, + ["pgfsys@animation@offset"] = { + arguments = {{meta = "time offset"}, {meta = "begin or end"}}, + details = [[ +Specifies that (in addition to any other beginnings or endings) the +animation's timeline should begin (or end) ⟨time offset⟩ many seconds +after the graphic is shown. For instance, in the next example the +animation will start automatically after 5 s *or* when then button is +pressed. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyoffset{5}{begin} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@offset" + }, + ["pgfsys@animation@removeatend"] = { + details = [[ +The opposite of `\pgfsysanimkeyfreezeatend`. This is the default. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyremoveatend + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@removeatend" + }, + ["pgfsys@animation@repeat"] = { + arguments = {{meta = "number of times"}}, + details = [[ +Specifies that the animation should repeat the specified ⟨number of +times⟩, which may be a fractional number. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrepeat{2.5} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@repeat" + }, + ["pgfsys@animation@repeat@dur"] = { + arguments = {{meta = "seconds"}}, + details = [[ +Specifies that the animation should repeat until ⟨seconds⟩ have elapsed. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrepeatdur{5} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@repeat@dur" + }, + ["pgfsys@animation@repeat@event"] = { + arguments = { + {meta = "id"}, + {meta = "type"}, + {meta = "repeat count"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ +The animation begins (or end) with a certain offset when another +animation has reached a certain repeat count. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-5mm} + \pgfsysanimkeyrepeatdur{5} + \pgfsys@new@id{\animationid} + \pgfsys@use@id{\animationid} + \pgfsysanimate{translate} + \global\let\animationid\animationid } + \tikz { + \pgfidrefnextuse{\objid}{other} + \pgfsysanimkeyrepeatevent{\animationid}{}{2}{0}{begin} + \pgfsysanimkeysnapshotstart{4} + \pgfsysanimkeywhom{\objid}{} + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-5mm} + \pgfsysanimate{translate} + \node [fill=red, text=white, circle] (other) {Other}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@repeat@event" + }, + ["pgfsys@animation@repeat@indefinite"] = { + details = [[ +Specifies that the animation should repeat indefinitely. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrepeatindefinite + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@repeat@indefinite" + }, + ["pgfsys@animation@restart@always"] = { + details = [[ +Defines that the animation can be restarted at any time. This is the +default. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrestartalways + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@restart@always" + }, + ["pgfsys@animation@restart@never"] = { + details = [[ +Defines that the animation cannot be restarted once it has run. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrestartnever + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@restart@never" + }, + ["pgfsys@animation@restart@whennotactive"] = { + details = [[ +Defines that the animation cannot be restarted while it is running. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrestartwhennotactive + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@restart@whennotactive" + }, + ["pgfsys@animation@rotatealong"] = { + details = [[ +Indicates that the to-be-animated group should be rotated automatically +so that it points along the path as time progresses. This option is only +applicable to motion animations. + + \animationexample{node}{}{ + \pgfsysanimkeyrotatealong + \pgfsysanimkeymovealong{% + \pgfsyssoftpath@movetotoken{0pt}{0pt}% + \pgfsyssoftpath@linetotoken{0pt}{-5mm}% + \pgfsyssoftpath@curvetosupportatoken{0pt}{-1cm}% + \pgfsyssoftpath@curvetosupportbtoken{0pt}{-1cm}% + \pgfsyssoftpath@curvetotoken{-5mm}{-1cm}} + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalscalar{0}% + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalscalar{1} + \pgfsysanimate{motion} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@rotatealong" + }, + ["pgfsys@animation@syncbegin"] = { + arguments = { + {meta = "sync base id"}, + {meta = "type"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ +Specifies that the animation should begin ⟨time offset⟩ many seconds +after the ⟨sync base id⟩ with the given ⟨type⟩ has begun. Here, the +⟨sync base id⟩ must have been obtained using `\pgfsys@new@id`. + +The idea behind a sync base is that you setup an animation and name it, +other animations can start alongside this animation. An animation whose +sole purpose is to orchestrate other animations in this way is called a +*sync base*. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@syncbegin" + }, + ["pgfsys@animation@syncend"] = { + arguments = { + {meta = "sync base id"}, + {meta = "type"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ +Works like `\pgfsysanimkeysyncbegin` only the animation begin (or ends) +when the sync base ends. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@syncend" + }, + ["pgfsys@animation@time"] = { + arguments = { + {meta = "time"}, + {meta = "entry spline control x"}, + {meta = "entry spline control y"}, + {meta = "exit spline control x"}, + {meta = "exit spline control y"} + }, + details = [[ +The ⟨time⟩ is a number representing seconds (so `0.5` means 500 ms). + +The spline between a time--value pair and the next is specified using +the four parameters following the time. The first two of these specify +the second control point of the interval preceding the time--value pair +(called the "entry" control point), the last two parameters specify the +first control point of the interval following the pair (called the +"exit" control point). Consider for instance, the following calls: + + \pgfsysanimkeytime{10}{0.1}{0.2}{0.3}{0.4} + \pgfsysanimvalscalar{100} + \pgfsysanimkeytime{15}{0.5}{0.6}{0.7}{0.8} + \pgfsysanimvalscalar{200} + +This will create (at least) the time interval +$[10\,\mathrm s,15\,\mathrm + s]$ and the control points for this interval will be $(0.3,0.4)$ and +$(0.5,0.6)$. + +Control points are specified in a different "coordinate" system from the +time--value pairs themselves: While the time--value pairs are specified +using a number representing seconds and a value using some special +commands, the control points are specified as numbers between $0$ and +$1$, each time representing a fraction of the time interval or the value +interval. In the example, the time interval is +$[10\,\mathrm s,15\,\mathrm + s]$ and the value interval is $[100,200]$. This means that a control +point of $(0.3,0.4)$ actually refers to the time--value +$(11.5\,\mathrm s,140)$. The "time--value curve" in the interval thus +"`(10s,100) .. controls (11.5s,140) and (12.5s,160) .. (15s,200)`". + +Note that by setting the control points always to $(1,1)$ and $(0,0)$ +you get a linear interpolation between time--value pairs. + +Two special cases are the following: When the two last parameters, the +exit spline, take the special values `stay` and `0`, the attribute's +value "stays" until the next value for the next time (it then "jumps" to +the next value then). This corresponds, roughly, to an "infinite" ⟨exit +spline control x⟩. Similarly, when the entry spline parameters take the +special values `jump` and `1`, the value immediately jumps from the +previous value to the next value when the previous value was specified. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@time" + }, + ["pgfsys@animation@tip@markers"] = { + arguments = {{meta = "start marker"}, {meta = "end marker"}}, + details = [[ +This command specifies that during a path animation the two markers +provided as parameters should be added (and rotated and moved along with +the path) at the start and end. The ⟨start marker⟩ must either be empty +(in which case no marker is added at the start) or it must be a macro +storing a value returned by the command `\pgfsys@marker@declare`. In +this case, the marker declared symbol will be added to the start during +the animation. The same situation applies to the end of the path. + +As pointed out earlier, only arrow tips / markers added to paths using +this command will be animated along with the path. In particular, you +should *not* add arrow tips to to-be-animated paths using +`\pgfsetarrow`. However, when you use a base value +(`\pgfsys@animation@base`) to set a path, the arrow tips will also be +added to this base path. + +To sum up, the "correct" way of adding arrow tips to a path that is +animated is to proceed as follows: + +1. You specify arrow tips for a path using this command. + +2. You specify times and values of the to-be-animated path, shortened + as necessary to accommodate the length of the arrow tips. + +3. You specify the first (or, possibly, some other) value in the + time--value sequence as a base value. + +4. You create a path animation that applies to a future path. + +5. You create this future path as an empty path without arrow tips and + draw it. Because of the setting of the base value, instead of the + empty path the base path will be used as the "real" path and the + animation's arrow tips will be added as arrow tips. + +When you have more than one animation for a given path, these different +animations may use different arrow tips / markers. This allows you to +animate (change) which arrow tip is used on a path over time. + + % Declare a marker: + \pgfsys@marker@declare\mymarker{% + \pgfscope% + \pgfsetcolor{red!75}% + \pgfpathmoveto{\pgfpoint{0pt}{5pt}}\pgfpathlineto{\pgfpoint{8pt}{0pt}}% + \pgfpathlineto{\pgfpoint{0pt}{0pt}}\pgfpathclose% + \pgfusepathqfill% + \endpgfscope% + \pgfpathmoveto{\pgfpoint{0pt}{5pt}}\pgfpathlineto{\pgfpoint{8pt}{0pt}}% + \pgfpathlineto{\pgfpoint{0pt}{-5pt}}\pgfpathclose% + \pgfusepathqstroke% + }% + \animationexample{my path}{path}{ + \pgfsysanimkeytipmarkers{\mymarker}{\mymarker} + \pgfsysanimkeybase + \pgfsysanimvalpath{\pgfsys@moveto{1cm}{0cm}% + \pgfsys@lineto{1cm}{1cm}% + \pgfsys@lineto{2cm}{0cm}} + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalpath{\pgfsys@moveto{1cm}{0cm}% + \pgfsys@lineto{1cm}{1cm}% + \pgfsys@lineto{2cm}{0cm}} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalpath{\pgfsys@moveto{1cm}{1cm}% + \pgfsys@lineto{2cm}{1cm}% + \pgfsys@lineto{1cm}{0cm}} + \pgfsysanimate{path} + \filldraw [ultra thick,draw=blue,fill=blue!20, name=my path]; + \path (1,0) (2,1);} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@tip@markers" + }, + ["pgfsys@animation@val@color@cmy"] = { + arguments = {{meta = "cyan"}, {meta = "magenta"}, {meta = "yellow"}}, + details = [[ +Like the `\pgfsysanimvalcolorcmyk` only without the black part. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@color@cmy" + }, + ["pgfsys@animation@val@color@cmyk"] = { + arguments = { + {meta = "cyan"}, + {meta = "magenta"}, + {meta = "yellow"}, + {meta = "black"} + }, + details = [[ +Creates a time--value pairs where the value is color specified by four +fractional values between 0 and 1 for the cyan, magenta, yellow, and +black part. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@color@cmyk" + }, + ["pgfsys@animation@val@color@gray"] = { + arguments = {{meta = "gray value"}}, + details = [[ +Creates a time--value pairs where the value is gray value (a fraction +between 0 and 1). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@color@gray" + }, + ["pgfsys@animation@val@color@rgb"] = { + arguments = {{meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ +Creates a time--value pairs where the value is color specified by three +fractional values between 0 and 1 for the red, the green, and the blue +part. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@color@rgb" + }, + ["pgfsys@animation@val@current"] = { + details = [[ +Creates a time--value pairs where the value is the current value that +the attribute has. This command can only be used in conjunction with +"real" animations, when you use it with a snapshot an error is raised. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@current" + }, + ["pgfsys@animation@val@dash"] = { + arguments = {{meta = "pattern"}, {meta = "phase"}}, + details = [[ +Creates a time--value pairs where the value is dash pattern and phase +with the same syntax as `\pgfsys@setdash`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@dash" + }, + ["pgfsys@animation@val@dimension"] = { + arguments = {{meta = "dimension"}}, + details = [[ +Creates a time--value pairs where the value is a TeX dimension like +`0.5pt` or `-2in`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@dimension" + }, + ["pgfsys@animation@val@path"] = { + arguments = {{meta = "low-level path construction command"}}, + details = [[ +Creates a time--value pairs where the value is path. The ⟨low-level +commands⟩ must consist of a sequence of path construction commands like +`\pgfsys@lineto` or `\pgfsyssoftpath@linetotoken` (more precisely, the +commands must form a list of TeX tokens and dimensions surrounded by +braces). For each call of this command, the sequence of tokens and +numbers must be the some. During the animation, only and exactly the +numbers will be interpolated. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@path" + }, + ["pgfsys@animation@val@scalar"] = { + arguments = {{meta = "number"}}, + details = [[ +Creates a time--value pairs where the value is a number like `0.5` or +`-2.25`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@scalar" + }, + ["pgfsys@animation@val@scale"] = { + arguments = {{meta = "x scale"}, {meta = "y scale"}}, + details = [[ +Creates a time--value pairs where the value is pair of scalar values. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@scale" + }, + ["pgfsys@animation@val@text"] = { + arguments = {{meta = "text"}}, + details = [[ +Creates a time--value pairs where the value is some text. Which texts +are permissible depends on the to-be-animated attribute. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@text" + }, + ["pgfsys@animation@val@translate"] = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ +Creates a time--value pairs where the value is a coordinate. The +dimensions must be TeX dimensions. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@translate" + }, + ["pgfsys@animation@val@viewbox"] = { + arguments = { + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"} + }, + details = [[ +Creates a time--value pairs where the value is view box. The lower left +corner is given by $(x_1,y_1)$, consisting of two TeX dimensions, and +the upper right corner is $(x_2,y_2)$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@viewbox" + }, + ["pgfsys@animation@whom"] = { + arguments = {{meta = "id"}, {meta = "type"}}, + details = [[ +Sets the target of the animation. The `{id}` must previously have been +created using `\pgfsys@new@id`, `{type}` must be a type (the empty type +is also allowed). See Section ?? for details on ids and types. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@whom" + }, + ["pgfsys@append@type"] = { + arguments = {{meta = "text"}}, + details = [[ +Appends the ⟨text⟩ to the current type. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@append@type" + }, + ["pgfsys@attach@to@id"] = { + arguments = { + {meta = "id"}, + {meta = "type"}, + {meta = "begin code"}, + {meta = "end code"}, + {meta = "setup code"} + }, + details = [[ +Attaches codes to the ⟨id⟩-⟨type⟩-pair, where ⟨id⟩ must have been +created using `\pgfsys@new@id`. The effect is that just before the id +scope for this pair is created, the ⟨setup code⟩ is executed, then the +scope is started, then the ⟨begin code⟩ is executed at the beginning, +and, finally, ⟨end code⟩ gets executed just before the scope ends. +Multiple calls of this macro accumulated. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@attach@to@id" + }, + ["pgfsys@begin@idscope"] = { + details = [[ +Starts a (graphics) scope whose sole purpose is to assign it an +id-type-pair so that it can be referenced later. Note that this command +does not always produce a graphics scope: If not id is currently in use +or if the id-type-pair has already been used, a graphic scope may or may +not be created as defined by the driver (but always a TeX scope). This +allows drivers to minimize the number of graphic scopes created. + +When an id scope is created, any code that has been "attached" to it +using `\pgfsys@attach@to@id` gets executed, see that command. + +Note that `\pgfsys@beginscope` does not use the current id-type-pair. +You need to call this command to attach an id to a group. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@begin@idscope" + }, + ["pgfsys@begininvisible"] = { + details = [[ +Between this command and the closing `\pgfsys@endinvisible` all output +should be suppressed. Nothing should be drawn at all, which includes all +paths, images and shadings. However, no groups (neither TeX groups nor +graphic state groups) should be opened by this command. + +This command has a default implementation and need not be implemented by +a driver file. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@begininvisible" + }, + ["pgfsys@beginpicture"] = { + details = [[ +Called at the beginning of a `{pgfpicture}`. This command should "set up +things". + +Most drivers will need to implement this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@beginpicture" + }, + ["pgfsys@beginpurepicture"] = { + details = [[ +This version of the `\pgfsys@beginpicture` picture command can be used +for pictures that are guaranteed not to contain any escaped boxes (see +below). In this case, a driver might provide a more compact version of +the command. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@beginpurepicture" + }, + ["pgfsys@beginscope"] = { + details = [[ +Saves the current graphic state on a graphic state stack. All changes to +the graphic state parameters mentioned for `\pgfsys@stroke` and +`\pgfsys@fill` will be local to the current graphic state and the old +values will be restored after `\pgfsys@endscope` is used. + +*Warning:* PDF and PostScript differ with respect to the question of +whether the current path is part of the graphic state or not. For this +reason, you should never use this command unless the path is currently +empty. For example, it might be a good idea to use `\pgfsys@discardpath` +prior to calling this command. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@beginscope" + }, + ["pgfsys@beveljoin"] = { + details = [[ +Sets the join to a bevel join. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@beveljoin" + }, + ["pgfsys@blend@mode"] = { + arguments = {{meta = "value"}}, + details = [[ +Sets the blend mode, see Section 7.2.4 of the PDF Specification, +Version 1.7. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@blend@mode" + }, + ["pgfsys@buttcap"] = { + details = [[ +Sets the cap to a butt cap. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@buttcap" + }, + ["pgfsys@clipfading"] = { + details = [[ +This command has a default implementation and need not be implemented by +driver files other than `pgfsys-dvips.def`. The macro is called in +`\pgfsetfadingforcurrentpath` and `\pgfsetfadingforcurrentpathstroked` +of the basic layer, where it invokes the current path for clipping the +shading just before installing it as an opacity mask for fading. The +default implementation is actually a non-operation, but with `dvips` it +is used to clip the fading as described. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@clipfading" + }, + ["pgfsys@clipnext"] = { + details = [[ +This command should be issued after a path has been constructed, but +before it has been stroked and/or filled or discarded. When the command +is used, the next stroking/filling/discarding command will first be +executed normally. Then, afterwards, the just-used path will be used for +subsequent clipping. If there has already been a clipping region, this +region is intersected with the new clipping path (the clipping cannot +get bigger). The nonzero winding number rule is used to determine +whether a point is inside or outside the clipping area or the even-odd +rule, depending on whether `\ifpgfsys@eorule` holds. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@clipnext" + }, + ["pgfsys@closepath"] = { + details = [[ +Close the current path. This results in joining the current point of the +path with the point specified by the last `\pgfsys@moveto` operation. +Typically, this is preferable over using `\pgfsys@lineto` to the last +point specified by a `\pgfsys@moveto`, since the line starting at this +point and the line ending at this point will be smoothly joined by +`\pgfsys@closepath`. + +Consider + + \pgfsys@moveto{0pt}{0pt} + \pgfsys@lineto{10bp}{10bp} + \pgfsys@lineto{0bp}{10bp} + \pgfsys@closepath + \pgfsys@stroke + +and + + \pgfsys@moveto{0bp}{0bp} + \pgfsys@lineto{10bp}{10bp} + \pgfsys@lineto{0bp}{10bp} + \pgfsys@lineto{0bp}{0bp} + \pgfsys@stroke + +The difference between the above will be that in the second triangle the +corner at the origin will be wrong; it will just be the overlay of two +lines going in different directions, not a sharp pointed corner. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@closepath" + }, + ["pgfsys@closestroke"] = { + details = [[ +This command should have the same effect as first closing the path and +then stroking it. + +This command has a default implementation and need not be implemented by +a driver file. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@closestroke" + }, + ["pgfsys@color@cmy"] = { + arguments = {{meta = "cyan"}, {meta = "magenta"}, {meta = "yellow"}}, + details = [[ +Sets the color used for stroking and filling operations to the given cmy +tuple (numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmy" + }, + ["pgfsys@color@cmy@fill"] = { + arguments = {{meta = "cyan"}, {meta = "magenta"}, {meta = "yellow"}}, + details = [[ +Sets the color used for filling operations to the given cmy tuple +(numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmy@fill" + }, + ["pgfsys@color@cmy@stroke"] = { + arguments = {{meta = "cyan"}, {meta = "magenta"}, {meta = "yellow"}}, + details = [[ +Sets the color used for stroking operations to the given cmy tuple +(numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmy@stroke" + }, + ["pgfsys@color@cmyk"] = { + arguments = { + {meta = "cyan"}, + {meta = "magenta"}, + {meta = "yellow"}, + {meta = "black"} + }, + details = [[ +Sets the color used for stroking and filling operations to the given +cmyk tuple (numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmyk" + }, + ["pgfsys@color@cmyk@fill"] = { + arguments = { + {meta = "cyan"}, + {meta = "magenta"}, + {meta = "yellow"}, + {meta = "black"} + }, + details = [[ +Sets the color used for filling operations to the given cmyk tuple +(numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmyk@fill" + }, + ["pgfsys@color@cmyk@stroke"] = { + arguments = { + {meta = "cyan"}, + {meta = "magenta"}, + {meta = "yellow"}, + {meta = "black"} + }, + details = [[ +Sets the color used for stroking operations to the given cmyk tuple +(numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmyk@stroke" + }, + ["pgfsys@color@gray"] = { + arguments = {{meta = "black"}}, + details = [[ +Sets the color used for stroking and filling operations to the given +black value, where 0 means black and 1 means white. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@gray" + }, + ["pgfsys@color@gray@fill"] = { + arguments = {{meta = "black"}}, + details = [[ +Sets the color used for filling operations to the given black value, +where 0 means black and 1 means white. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@gray@fill" + }, + ["pgfsys@color@gray@stroke"] = { + arguments = {{meta = "black"}}, + details = [[ +Sets the color used for stroking operations to the given black value, +where 0 means black and 1 means white. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@gray@stroke" + }, + ["pgfsys@color@reset"] = { + details = [[ +This command will be called when the `\color` command is used. It should +purge any internal settings of stroking and filling color. After this +call, till the next use of a command like `\pgfsys@color@rgb@fill`, the +current color installed by the `\color` command should be used. + +If the TeX-if `\pgfsys@color@reset@inorder` is set to true, this command +may "assume" that any call to a color command that sets the fill or +stroke color came "before" the call to this command and may try to +optimize the output accordingly. + +An example of an incorrect "out of order" call would be using +`\pgfsys@color@reset` at the beginning of a box that is constructed +using `\setbox`. Then, when the box is constructed, no special fill or +stroke color might be in force. However, when the box is later on +inserted at some point, a special fill color might already have been +set. In this case, this command is not guaranteed to reset the color +correctly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@reset" + }, + ["pgfsys@color@reset@inorderfalse"] = { + details = [[ +Switches off the optimized color resetting. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@reset@inorderfalse" + }, + ["pgfsys@color@reset@inordertrue"] = { + details = [[ +Sets the optimized "in order" version of the color resetting. This is +the default. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@reset@inordertrue" + }, + ["pgfsys@color@rgb"] = { + arguments = {{meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ +Sets the color used for stroking and filling operations to the given +red/green/blue tuple (numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@rgb" + }, + ["pgfsys@color@rgb@fill"] = { + arguments = {{meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ +Sets the color used for filling operations to the given red/green/blue +tuple (numbers between 0 and 1). This color may be different from the +stroking color. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@rgb@fill" + }, + ["pgfsys@color@rgb@stroke"] = { + arguments = {{meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ +Sets the color used for stroking operations to the given red/green/blue +tuple (numbers between 0 and 1). + +Make stroked text dark red: `\pgfsys@color@rgb@stroke{0.5}{0}{0}` + +The special stroking color is only used if the stroking color has been +set since the last `\color` or `\pgfsys@color@...` command. Thus, each +`\color` command will reset both the stroking and filling colors by +calling `\pgfsys@color@reset`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@rgb@stroke" + }, + ["pgfsys@color@unstacked"] = { + arguments = {{meta = "\\LaTeX\\ color"}}, + details = [[ +This slightly obscure command causes the color stack to be tricked. When +called, this command should set the current color to ⟨LaTeX color⟩ +without causing any change in the color stack. + +`\pgfsys@color@unstacked{red}` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@unstacked" + }, + ["pgfsys@curveto"] = { + arguments = { + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"}, + {meta = "$x_3$"}, + {meta = "$y_3$"} + }, + details = [[ +Continue the current path to $(x_3,y_3)$ with a Bézier curve that has +the two control points $(x_1,y_1)$ and $(x_2,y_2)$. + +Draw a good approximation of a quarter circle: + + \pgfsys@moveto{10pt}{0pt} + \pgfsys@curveto{10pt}{5.55pt}{5.55pt}{10pt}{0pt}{10pt} + \pgfsys@stroke + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@curveto" + }, + ["pgfsys@declarepattern"] = { + arguments = { + {meta = "name"}, + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"}, + {meta = "$x$ step"}, + {meta = "$y$ step"}, + {meta = "$a$"}, + {meta = "$b$"}, + {meta = "$c$"}, + {meta = "$d$"} + }, + details = [[ +This command declares a new colored or uncolored pattern, depending on +whether ⟨flag⟩ is `0`, which means uncolored, or `1`, which means +colored. Uncolored patterns have no inherent color, the color is +provided when they are set. Colored patters have an inherent color. + +The ⟨name⟩ is a name for later use when the pattern is to be shown. The +pairs $(x_1,y_1)$ and $(x_2,y_2)$ must describe a bounding box of the +pattern ⟨code⟩. + +The tiling step of the pattern is given by ⟨$x$ step⟩ and ⟨$y$ step⟩. + +The parameters ⟨$a$⟩ to ⟨$f$⟩ are entries of the transformation matrix +that is applied to the pattern, see `\pgfsys@patternmatrix` for more +information. + + \pgfsys@declarepattern + {hori}{-.5pt}{0pt}{.5pt}{3pt}{3pt}{3pt}% + {1.0}{0.0}{0.0}{1.0}{0.0pt}{0.0pt}% + {\pgfsys@moveto{0pt}{0pt}\pgfsys@lineto{0pt}{3pt}\pgfsys@stroke} + {0} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@declarepattern" + }, + ["pgfsys@defineimage"] = { + details = [[ +Called, when an image should be defined. + +This command does not take any parameters. Instead, certain macros will +be preinstalled with appropriate values when this command is invoked. +These are: + +- `\pgf@filename` File name of the image to be defined. + +- `\pgf@imagewidth` Will be set to the desired (scaled) width of the + image. + +- `\pgf@imageheight` Will be set to the desired (scaled) height of the + image. + + If this macro and also the height macro are empty, the image should + have its "natural" size. + + If only one of them is specified, the undefined value the image is + scaled so that the aspect ratio is kept. + + If both are set, the image is scaled in both directions + independently, possibly changing the aspect ratio. + +The following macros presumable mostly make sense for drivers that can +handle PDF: + +- `\pgf@imagepage` The desired page number to be extracted from a + multi-page "image". + +- `\pgf@imagemask` If set, it will be set to `/SMask x 0 R` where `x` + is the PDF object number of a soft mask to be applied to the image. + +- `\pgf@imageinterpolate` If set, it will be set to + `/Interpolate true` or `/Interpolate false`, indicating whether the + image should be interpolated in PDF. + +The command should now set up the macro `\pgf@image` such that calling +this macro will result in typesetting the image. Thus, `\pgf@image` is +the "return value" of the command. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@defineimage" + }, + ["pgfsys@definemask"] = { + details = [[ +This command declares a fading (known as a soft mask in this context) +based on an image and for usage with images. It works similar to +`\pgfsys@defineimage`: Certain macros are set when the command is +called. The result should be to set the macro `\pgf@mask` to a pdf +object count that can subsequently be used as a transparency mask. The +following macros will be set when this command is invoked: + +- `\pgf@filename` File name of the mask to be defined. + +- `\pgf@maskmatte` The so-called matte of the mask (see the + PDF documentation for details). The matte is a color specification + consisting of 1, 3 or 4 numbers between 0 and 1. The number of + numbers depends on the number of color channels in the image (not in + the mask!). It will be assumed that the image has been preblended + with this color. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@definemask" + }, + ["pgfsys@defobject"] = { + arguments = { + {meta = "name"}, + {meta = "lower left"}, + {meta = "upper right"}, + {meta = "code"} + }, + details = [[ +Declares an object for later use. The idea is that the object can be +precached in some way and then be rendered more quickly when used +several times. For example, an arrow head might be defined and +prerendered in this way. + +The parameter ⟨name⟩ is the name for later use. ⟨lower left⟩ and ⟨upper +right⟩ are PGF points specifying a bounding box for the object. ⟨code⟩ +is the code for the object. The code should not be too fancy. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@defobject" + }, + ["pgfsys@discardpath"] = { + details = [[ +Normally, this command should "throw away" the current path. However, +after `\pgfsys@clipnext` has been called, the current path should +subsequently be used for clipping. See `\pgfsys@clipnext` for details. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@discardpath" + }, + ["pgfsys@end@idscope"] = { + details = [[ +Ends the graphics id scope started by `\pgfsys@end@idscope`. It must +nest correctly with other graphic scopes and TeX scopes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@end@idscope" + }, + ["pgfsys@endinvisible"] = { + details = [[ +Ends the invisibility section, unless invisibility blocks have been +nested. In this case, only the "last" one restores visibility. + +This command has a default implementation and need not be implemented by +a driver file. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@endinvisible" + }, + ["pgfsys@endpicture"] = { + details = [[ +Called at the end of a `{pgfpicture}`. + +Most drivers will need to implement this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@endpicture" + }, + ["pgfsys@endpurepicture"] = { + details = [[ +Called at the end of a "pure" `{pgfpicture}`. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@endpurepicture" + }, + ["pgfsys@endscope"] = { + details = [[ +Restores the last saved graphic state. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@endscope" + }, + ["pgfsys@endviewbox"] = { + details = [[ +Ends a viewbox previously started using `\pgfsys@viewboxmeet` or the +`...slice` variant. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@endviewbox" + }, + ["pgfsys@fadingfrombox"] = { + arguments = {{meta = "name"}, {meta = "box"}}, + details = [[ +Declares the fading ⟨name⟩. The ⟨box⟩ is a TeX-box. Its content's +luminosity determines the opacity of the resulting fading. This means +that the lighter a pixel inside the box, the more opaque the fading will +be at this position. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@fadingfrombox" + }, + ["pgfsys@fill"] = { + details = [[ +This command fills the area surrounded by the current path. If the path +has not yet been closed, it is closed prior to filling. The path itself +is not stroked. For self-intersecting paths or paths consisting of +multiple parts, the nonzero winding number rule is used to determine +whether a point is inside or outside the path, except if +`\ifpgfsys@eorule` holds -- in which case the even-odd rule should be +used. (See the PDF or PostScript manual for details.) + +The following graphic state parameters influence the filling: + +Interior rule +If `\ifpgfsys@eorule` is set, the even-odd rule is used, otherwise the +non-zero winding number rule. + +Fill color +If the fill color is not especially set, the current color is used. + +Clipping area +If a clipping area is established, only those parts of the filling area +that are inside the clipping area will be drawn. + +In addition to filling the path, the path will also be used for clipping +if `\pgfsys@clipnext` is used prior to this command. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@fill" + }, + ["pgfsys@fill@opacity"] = { + arguments = {{meta = "value"}}, + details = [[ +Sets the opacity of filling operations. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@fill@opacity" + }, + ["pgfsys@fillstroke"] = { + details = [[ +First, the path is filled, then the path is stroked. If the fill and +stroke colors are the same (or if they are not specified and the current +color is used), this yields almost the same as a `\pgfsys@fill`. +However, due to the line thickness of the stroked path, the fill-stroked +area will be slightly larger. + +In addition to stroking and filling the path, the path will also be used +for clipping if `\pgfsys@clipnext` is used prior to this command. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@fillstroke" + }, + ["pgfsys@functionalshading"] = { + arguments = { + {meta = "name"}, + {meta = "lower left corner"}, + {meta = "upper right corner"}, + {meta = "type 4 function"} + }, + details = [[ +Declares a shading using a PostScript-like function that provides a +color for each point. Like the previous macros, this command should set +up the macro `\@pgfshading`⟨name⟩`!` so that it will produce a box +containing the desired shading. + +Parameter ⟨name⟩ is the name of the shading. Parameter ⟨type 4 function⟩ +is a Postscript-like function (type 4 function of the PDF specification) +as described in Section 3.9.4 of the PDF specification version 1.7. +Parameters ⟨lower left corner⟩ and ⟨upper right corner⟩ are PGF points +that specifies the lower left and upper right corners of the shading, +respectively. + +When ⟨type 4 function⟩ is evaluated, the coordinate of the current point +will be on the (virtual) PostScript stack in bp units. After the +function has been evaluated, the stack should consist of three numbers +(not integers! -- the Apple PDF renderer is broken in this regard, so +add cvrs at the end if needed) that represent the red, green, and blue +components of the color. + +A buggy function will result is *totally unpredictable chaos* during +rendering. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@functionalshading" + }, + ["pgfsys@getposition"] = { + arguments = {{meta = "name"}, {meta = "macro"}}, + details = [[ +This command retrieves a position that has been marked on an earlier run +of TeX on the current file. The ⟨macro⟩ must be a macro name such as +`\mymacro`. It will be redefined such that it is + +- either just `\relax` or + +- a `\pgfpoint...` command. + +The first case will happen when the position has not been marked at all +or when the file is typeset for the first time, when the coordinates are +not yet available. + +In the second case, executing ⟨macro⟩ yields the position on the page +that is to be interpreted as follows: A coordinate like +`\pgfpoint{2cm}{3cm}` means "2cm to the right and 3cm up from the origin +of the page". The position of the origin of the page is not guaranteed +to be at the lower left corner, it is only guaranteed that all pictures +on a page use the same origin. + +To determine the lower left corner of a page, you can call +`\pgfsys@getposition` with ⟨name⟩ set to the special name +`pgfpageorigin`. By shifting all positions by the amount returned by +this call you can position things absolutely on a page. + +Referencing a point of the page: + + The value of $x$ is \pgfsys@markposition{here}important. + + Lots of text. + + \hbox{\pgfsys@markposition{myorigin}% + \begin{pgfpicture} + % Switch of size protocol + \pgfpathmoveto{\pgfpointorigin} + \pgfusepath{use as bounding box} + + \pgfsys@getposition{here}{\hereposition} + \pgfsys@getposition{myorigin}{\thispictureposition} + + \pgftransformshift{\pgfpointscale{-1}{\thispictureposition}} + \pgftransformshift{\hereposition} + + \pgfpathcircle{\pgfpointorigin}{1cm} + \pgfusepath{draw} + \end{pgfpicture}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@getposition" + }, + ["pgfsys@global@papersize"] = { + arguments = {{meta = "width"}, {meta = "height"}}, + details = [[ +Like the previous command, only for drivers where setting the paper size +parameters is a TeX-group-local operation, `\global` is prefixed to the +setting of the page sizes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@global@papersize" + }, + ["pgfsys@hbox"] = { + arguments = {{meta = "box number"}}, + details = [[ +Called to insert a (horizontal) TeX box inside a `{pgfpicture}`. + +Most drivers will need to (re-)implement this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@hbox" + }, + ["pgfsys@hboxsynced"] = { + arguments = {{meta = "box number"}}, + details = [[ +Called to insert a (horizontal) TeX box inside a `{pgfpicture}`, but +with the current coordinate transformation matrix synced with the canvas +transformation matrix. + +This command should do the same as if you used `\pgflowlevelsynccm` +followed by `\pgfsys@hbox`. However, the default implementation of this +command will use a "TeX-translation" for the translation part of the +transformation matrix. This will ensure that hyperlinks "survive" at +least translations. On the other hand, a driver may choose to revert to +a simpler implementation. This is done, for example, for the SVG +implementation, where a TeX-translation makes no sense. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@hboxsynced" + }, + ["pgfsys@horishading"] = { + arguments = {{meta = "name"}, {meta = "height"}, {meta = "specification"}}, + details = [[ +Declares a horizontal shading for later use. The effect of this command +should be the definition of a macro called `\@pgfshading`⟨name⟩`!` (or +`\csname @pdfshading`⟨name⟩`!\endcsname`, to be precise). When invoked, +this new macro should insert a shading at the current position. + +⟨name⟩ is the name of the shading, which is also used in the output +macro name. ⟨height⟩ is the height of the shading and must be given as a +TeX dimension like `2cm` or `10pt`. ⟨specification⟩ is a shading color +specification as specified in Section ??. The shading specification +implicitly fixes the width of the shading. + +When `\@pgfshading`⟨name⟩`!` is invoked, it should insert a box of +height ⟨height⟩ and the width implicit in the shading declaration. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@horishading" + }, + ["pgfsys@imagesuffixlist"] = { + details = [[ +This macro should expand to a list of suffixes, separated by ':', that +will be tried when searching for an image. + +`\def\pgfsys@imagesuffixlist{eps:epsi:ps}` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@imagesuffixlist" + }, + ["pgfsys@invoke"] = { + arguments = {{meta = "literals"}}, + details = [[ +This command gets protocolled literals and should insert them into the +`.pdf` or `.dvi` file using an appropriate `\special`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@invoke" + }, + ["pgfsys@lineto"] = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +Continue the current path to $(x,y)$ with a straight line. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@lineto" + }, + ["pgfsys@marker@declare"] = { + arguments = {{meta = "macro"}, {meta = "code"}}, + details = [[ +Declares a *marker* symbol for later use. The command is very similar to +`\pgfsys@defobject`, but the use case is slightly different: The graphic +object defined using the ⟨code⟩ is stored in such a way that it can be +used as an *arrow tip marker symbol* in animations. The ⟨macro⟩ is set +to an identifier by which the marker can be referenced later on. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@marker@declare" + }, + ["pgfsys@marker@use"] = { + arguments = {{meta = "macro"}}, + details = [[ +Adds the marker object referenced by the ⟨macro⟩ to the current output. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@marker@use" + }, + ["pgfsys@markposition"] = { + arguments = {{meta = "name"}}, + details = [[ +Marks a position on the page. This command should be given while normal +typesetting is done such as in + + The value of $x$ is \pgfsys@markposition{here}important. + +It causes the position `here` to be saved when the page is shipped out. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@markposition" + }, + ["pgfsys@miterjoin"] = { + details = [[ +Sets the join to a miter join. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@miterjoin" + }, + ["pgfsys@moveto"] = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +This command is used to start a path at a specific point $(x,y)$ or to +move the current point of the current path to $(x,y)$ without drawing +anything upon stroking (the current path is "interrupted"). + +Both ⟨x⟩ and ⟨y⟩ are given as TeX dimensions. It is the driver's job to +transform these to the coordinate system of the backend. Typically, this +means converting the TeX dimension into a dimensionless multiple of +$\frac{1}{72}\mathrm{in}$. The function `\pgf@sys@bp` helps with this +conversion. + +Draw a line from $(10\mathrm{pt},10\mathrm{pt})$ to the origin of the +picture. + + \pgfsys@moveto{10pt}{10pt} + \pgfsys@lineto{0pt}{0pt} + \pgfsys@stroke + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@moveto" + }, + ["pgfsys@new@id"] = { + arguments = {{meta = "macro"}}, + details = [[ +Creates a new id for later use and stores it in ⟨macro⟩. It is an +internal text created by the driver and may not be changed or modified. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@new@id" + }, + ["pgfsys@opacity"] = { + arguments = {{meta = "value"}}, + details = [[ +Sets the opacity of all operations, treating stroking and filling as a +transparency group. Some drivers support this operations, others do not +and set the fill and stroke individually. This difference can only be +seen when a path is stroked and filled at the same time: When the +drawing and fill opacities are set individually, the effect of filling +and drawing a path at the same time is the same as first filling the +path and then drawing it. On the other, if the opacity is set using this +command, the effect should rather be that same as first filling and then +drawing the path without any opacity in an off-screen area and then +copying the result to the target area with a homogeneous opacity of +⟨value⟩. + +Since PDF does not support this form of opacity, this command is only +present on the system layer and not supported in the basic layer. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@opacity" + }, + ["pgfsys@papersize"] = { + arguments = {{meta = "width"}, {meta = "height"}}, + details = [[ +Inserts the necessary `\special`s for the current driver into the output +stream to "locally" change the page size. Whether such a "local" change +is possible depends strongly on the driver. For instance, `dvips` will +honor the first call to this command that is part of the shipped-out +document and will ignore all other uses. In contrast, `pdftex` will use +the current value of the paper size for each page and, additionally, +setting the papersize is local to the current TeX group. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@papersize" + }, + ["pgfsys@patternmatrix"] = { + details = [[ +For convenience PGF defines the transformation matrix that is applied to +all patterns defined with `\pgfdeclarepatternformonly` and +`\pgfdeclarepatterninherentlycolored` in a macro. This can be used as an +extension point for ad-hoc transformation of existing patterns. The +default definition is the identity matrix: + + \def\pgfsys@patternmatrix{{1.0}{0.0}{0.0}{1.0}{0.0pt}{0.0pt}} + +The entries of the enclosed array +`{`⟨$a$⟩`}{`⟨$b$⟩`}{`⟨$c$⟩`}{`⟨$d$⟩`}{`⟨$e$⟩`}{`⟨$f$⟩`}` are entries in +the transformation matrix, identified as in the following transformation +prescription: $$\begin{pmatrix} + x' \\ + y' \\ + 1 \\ + \end{pmatrix} + = + \begin{pmatrix} + a & c & e \\ + b & d & f \\ + 0 & 0 & 1 \\ + \end{pmatrix} + \begin{pmatrix} + x \\ + y \\ + 1 \\ + \end{pmatrix} .$$ Carrying out the matrix multiplication results +in the following system of equations $$\begin{aligned} + x' &= a x + c y + e , \\ + y' &= b x + d y + f . + \end{aligned}$$ Evidently, the parameters `{a}` to `{d}` have to be +dimensionless because they are scaling factors, but the parameters `{e}` +and `{f}` are offsets, therefore they have to carry a unit. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@patternmatrix" + }, + ["pgfsys@pictureboxsynced"] = { + arguments = {{meta = "box number"}}, + details = [[ +Basically, this should do the same as doing a (scoped) low level sync +followed by inserting the box ⟨box number⟩ directly into the output +stream. However, the default implementation uses `\pgfsys@hboxsynced` in +conjunction with `\pgfsys@beginpicture` to ensure that, if possible, +hyperlinks survive in PDFs. Drivers that are sensitive to +picture-in-picture scopes should replace this implementation by + + \pgfsys@beginscope\pgflowlevelsynccm\box#1\pgfsys@endscope +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@pictureboxsynced" + }, + ["pgfsys@pop@type"] = { + details = [[ +Restores the most recently pushed type. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@pop@type" + }, + ["pgfsys@push@type"] = { + details = [[ +Pushes the current type on a global "stack of types" without opening a +TeX scope. The is useful when you temporarily wish to change the type +(for instance, by appending something to it), but you cannot create a +new scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@push@type" + }, + ["pgfsys@radialshading"] = { + arguments = { + {meta = "name"}, + {meta = "starting point"}, + {meta = "specification"} + }, + details = [[ +Declares a radial shading. Like the previous macros, this command should +set up the macro `\@pgfshading`⟨name⟩`!`, which upon invocation should +insert a radial shading whose size is implicit in ⟨specification⟩. + +The parameter ⟨starting point⟩ is a PGF point specifying the inner +starting point of the shading. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@radialshading" + }, + ["pgfsys@rdf@about"] = { + arguments = {{meta = "text"}}, + details = [[ +Adds the RDF attribute `about="`⟨text⟩`"` to the next id scope (please +see the RDFa specification for details on the semantics of `about` in +the context of the resource description framework). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@about" + }, + ["pgfsys@rdf@content"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@content" + }, + ["pgfsys@rdf@datatype"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@datatype" + }, + ["pgfsys@rdf@href"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@href" + }, + ["pgfsys@rdf@inlist"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@inlist" + }, + ["pgfsys@rdf@prefix"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@prefix" + }, + ["pgfsys@rdf@property"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@property" + }, + ["pgfsys@rdf@rel"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@rel" + }, + ["pgfsys@rdf@resource"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@resource" + }, + ["pgfsys@rdf@rev"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@rev" + }, + ["pgfsys@rdf@src"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@src" + }, + ["pgfsys@rdf@typeof"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@typeof" + }, + ["pgfsys@rdf@vocab"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@vocab" + }, + ["pgfsys@rect"] = { + arguments = {{meta = "x"}, {meta = "y"}, {meta = "width"}, {meta = "height"}}, + details = [[ +Append a rectangle to the current path whose lower left corner is at +$(x,y)$ and whose width and height in big points are given by ⟨width⟩ +and ⟨height⟩. + +This command can be "mapped back" to `\pgfsys@moveto` and +`\pgfsys@lineto` commands, but it is included since PDF has a special, +quick version of this command. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rect" + }, + ["pgfsys@rectcap"] = { + details = [[ +Sets the cap to a rectangular cap. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rectcap" + }, + ["pgfsys@roundcap"] = { + details = [[ +Sets the cap to a round cap. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@roundcap" + }, + ["pgfsys@roundjoin"] = { + details = [[ +Sets the join to a round join. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@roundjoin" + }, + ["pgfsys@setdash"] = { + arguments = {{meta = "pattern"}, {meta = "phase"}}, + details = [[ +Sets the dashing patter. ⟨pattern⟩ should be a list of TeX dimensions +separated by commas. ⟨phase⟩ should be a single dimension. + +`\pgfsys@setdash{3pt,3pt}{0pt}` + +The list of values in ⟨pattern⟩ is used to determine the lengths of the +"on" and "off" phases of the dashing. For example, if ⟨pattern⟩ is +`3bp,4bp`, then the dashing pattern is "3bp on followed by 4bp off, +followed by 3bp on, followed by 4bp off, and so on". A pattern of +`.5pt,4pt,3pt,1.5pt` means ".5pt on, 4pt off, 3pt on, 1.5pt off, .5pt +on, ..." If the number of entries is odd, the last one is used twice, so +`3pt` means "3pt on, 3pt off, 3pt on, 3pt off, ..." An empty list means +"always on". + +The second argument determines the "phase" of the pattern. For example, +for a pattern of `3bp,4bp` and a phase of `1bp`, the pattern would +start: "2bp on, 4bp off, 3bp on, 4bp off, 3bp on, 4bp off, ..." + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@setdash" + }, + ["pgfsys@setlinewidth"] = { + arguments = {{meta = "width"}}, + details = [[ +Sets the width of lines, when stroked, to ⟨width⟩, which must be a +TeX dimension. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@setlinewidth" + }, + ["pgfsys@setmiterlimit"] = { + arguments = {{meta = "factor"}}, + details = [[ +Sets the miter limit of lines to ⟨factor⟩. See the PDF or PostScript for +details on what the miter limit is. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@setmiterlimit" + }, + ["pgfsys@setpatterncolored"] = { + arguments = {{meta = "name"}}, + details = [[ +Sets the fill color to the pattern named ⟨name⟩. This pattern must have +been declared with the `1` flag. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@setpatterncolored" + }, + ["pgfsys@setpatternuncolored"] = { + arguments = {{meta = "name"}, {meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ +Sets the fill color to the pattern named ⟨name⟩. This pattern must +previously have been declared with ⟨flag⟩ set to `0`. The color of the +pattern is given in the parameters ⟨red⟩, ⟨green⟩, and ⟨blue⟩ in the +usual way. + +The fill color "pattern" will persist till the next color command that +modifies the fill color. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@setpatternuncolored" + }, + ["pgfsys@stroke"] = { + details = [[ +Stroke the current path (as if it were drawn with a pen). A number of +graphic state parameters influence this, which can be set using +appropriate system commands described later. + +Line width +The "thickness" of the line. A width of 0 is the thinnest width +renderable on the device. On a high-resolution printer this may become +invisible and should be avoided. A good choice is 0.4pt, which is the +default. + +Stroke color +This special color is used for stroking. If it is not set, the current +color is used. + +Cap +The cap describes how the endings of lines are drawn. A round cap adds a +little half circle to these endings. A butt cap ends the lines exactly +at the end (or start) point without anything added. A rectangular cap +ends the lines like the butt cap, but the lines protrude over the +endpoint by the line thickness. (See also the PDF manual.) If the path +has been closed, no cap is drawn. + +Join +This describes how a bend (a join) in a path is rendered. A round join +draws bends using small arcs. A bevel join just draws the two lines and +then fills the join minimally so that it becomes convex. A miter join +extends the lines so that they form a single sharp corner, but only up +to a certain miter limit. (See the PDF manual once more.) + +Dash +The line may be dashed according to a dashing pattern. + +Clipping area +If a clipping area is established, only those parts of the path that are +inside the clipping area will be drawn. + +In addition to stroking a path, the path may also be used for clipping +after it has been stroked. This will happen if the `\pgfsys@clipnext` is +used prior to this command, see there for details. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@stroke" + }, + ["pgfsys@stroke@opacity"] = { + arguments = {{meta = "value"}}, + details = [[ +Sets the opacity of stroking operations. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@stroke@opacity" + }, + ["pgfsys@thepageheight"] = { + details = [[ +This macro expands to the current page's height, provided LaTeX is used, +otherwise a best guess is returned (currently just `\the\vsize`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@thepageheight" + }, + ["pgfsys@thepagewidth"] = { + details = [[ +As above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@thepagewidth" + }, + ["pgfsys@transformcm"] = { + arguments = { + {meta = "a"}, + {meta = "b"}, + {meta = "c"}, + {meta = "d"}, + {meta = "e"}, + {meta = "f"} + }, + details = [[ +Perform a concatenation of the canvas transformation matrix with the +matrix given by the values ⟨a⟩ to ⟨f⟩, see the PDF or PostScript manual +for details. The values ⟨a⟩ to ⟨d⟩ are dimensionless factors, ⟨e⟩ and +⟨f⟩ are TeX dimensions + +`\pgfsys@transformcm{1}{0}{0}{1}{1cm}{1cm}`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@transformcm" + }, + ["pgfsys@transformshift"] = { + arguments = {{meta = "x displacement"}, {meta = "y displacement"}}, + details = [[ +This command will change the origin of the canvas to $(x,y)$. + +This command has a default implementation and need not be implemented by +a driver file. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@transformshift" + }, + ["pgfsys@transformxyscale"] = { + arguments = {{meta = "x scale"}, {meta = "y scale"}}, + details = [[ +This command will scale the canvas (and everything that is drawn) by a +factor of ⟨x scale⟩ in the $x$-direction and ⟨y scale⟩ in the +$y$-direction. Note that this applies to everything, including lines. So +a scaled line will have a different width and may even have a different +width when going along the $x$-axis and when going along the $y$-axis, +if the scaling is different in these directions. Usually, you do not +want this. + +This command has a default implementation and need not be implemented by +a driver file. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@transformxyscale" + }, + ["pgfsys@transparencygroupfrombox"] = { + arguments = {{meta = "box"}}, + details = [[ +This takes a TeX box and converts it into a transparency group. This +means that any transparency settings apply to the box as a whole. For +instance, if a box contains two overlapping black circles and you draw +the box and, thus, the two circles normally with 50% transparency, then +the overlap will be darker than the rest. By comparison, if the circles +are part of a transparency group, the overlap will get the same color as +the rest. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@transparencygroupfrombox" + }, + ["pgfsys@typesetpicturebox"] = { + arguments = {{meta = "box"}}, + details = [[ +Called *after* a `{pgfpicture}` has been typeset. The picture will have +been put in box ⟨box⟩. This command should insert the box into the +normal text. The box ⟨box⟩ will still be a "raw" box that contains only +the `\special`'s that make up the description of the picture. The job of +this command is to resize and shift ⟨box⟩ according to the baseline +shift and the size of the box. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@typesetpicturebox" + }, + ["pgfsys@use@id"] = { + arguments = {{meta = "id"}}, + details = [[ +"Uses" an id previously created using `\pgfsys@new@id`. This causes the +*next* graphic object to get the ⟨id⟩ (not the current one). Once used, +the id-type-pair becomes *invalid* and will not be attached to any other +graphics objects. It is, however, not an error to try this. If ⟨id⟩ is +empty, no id-type-pair is attached to the next object. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@use@id" + }, + ["pgfsys@use@type"] = { + arguments = {{meta = "type"}}, + details = [[ +Changes the type used with the next graphic object. As mentioned +earlier, the id assigned to the next object is actually a pair +consisting of the currently used id and the currently used type. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@use@type" + }, + ["pgfsys@usefading"] = { + arguments = { + {meta = "name"}, + {meta = "a"}, + {meta = "b"}, + {meta = "c"}, + {meta = "d"}, + {meta = "e"}, + {meta = "f"} + }, + details = [[ +Installs a previously declared fading ⟨name⟩ in the current graphics +state. Afterwards, all drawings will be masked by the fading. The fading +should be centered on the origin and have its original size, except that +the parameters ⟨a⟩ to ⟨f⟩ specify a transformation matrix that should be +applied additionally to the fading before it is installed. The +transformation should not apply to the following graphics, however. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@usefading" + }, + ["pgfsys@useobject"] = { + arguments = {{meta = "name"}, {meta = "extra code"}}, + details = [[ +Renders a previously declared object. The first parameter is the name of +the object. The second parameter is extra code that should be executed +right *before* the object is rendered. Typically, this will be some +transformation code. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@useobject" + }, + ["pgfsys@vertshading"] = { + arguments = {{meta = "name"}, {meta = "width"}, {meta = "specification"}}, + details = [[ +Like the horizontal version, only for vertical shadings. This time, the +height of the shading is implicit in ⟨specification⟩ and the width is +given as ⟨width⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@vertshading" + }, + ["pgfsys@viewboxmeet"] = { + arguments = { + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"}, + {meta = "$x'_1$"}, + {meta = "$y'_1$"}, + {meta = "$x'_2$"}, + {meta = "$y'_2$"} + }, + details = [[ +Starts a "view box" scope, which must be ended using +`\pgfsys@endviewbox` later on (with matching scopes). + +The effect of this command is as follows: Consider the rectangles $R$ +with lower left corner $(x_1,y_1)$ and upper right corner $(x_2,y_2)$ +and $R'$ with corners $(x'_1,y'_1)$ and $(x'_2,y'_2)$. The command will +install a canvas translation and uniform scaling such that $R'$ then has +the same center as $R$ and additionally, has maximum size such that it +still fits inside $R$. (Think of this as "viewing" $R'$ through $R$ such +that the aspect ratio is kept.) + +This command has a default implementation. Its main purpose is to allow +animations of the view box; for static drawings it is better to compute +the necessary transformations directly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@viewboxmeet" + }, + ["pgfsys@viewboxslice"] = { + arguments = { + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"}, + {meta = "$x'_1$"}, + {meta = "$y'_1$"}, + {meta = "$x'_2$"}, + {meta = "$y'_2$"} + }, + details = [[ +Works like the previous command, but now $R'$ has minimal size such that +it encompasses all of $R$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@viewboxslice" + }, + pgfsysanimate = { + arguments = {{meta = "attribute"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimate" + }, + pgfsysanimkeyaccesskey = { + arguments = { + {meta = "character"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyaccesskey" + }, + pgfsysanimkeyaccumulate = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyaccumulate" + }, + pgfsysanimkeybase = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeybase" + }, + pgfsysanimkeycanvastransform = { + arguments = {{meta = "pre"}, {meta = "post"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeycanvastransform" + }, + pgfsysanimkeyevent = { + arguments = { + {meta = "id"}, + {meta = "type"}, + {meta = "event name"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyevent" + }, + pgfsysanimkeyfreezeatend = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyfreezeatend" + }, + pgfsysanimkeymovealong = { + arguments = {{meta = "path"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeymovealong" + }, + pgfsysanimkeynoaccumulate = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeynoaccumulate" + }, + pgfsysanimkeynorotatealong = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeynorotatealong" + }, + pgfsysanimkeyoffset = { + arguments = {{meta = "time offset"}, {meta = "begin or end"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyoffset" + }, + pgfsysanimkeyremoveatend = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyremoveatend" + }, + pgfsysanimkeyrepeat = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrepeat" + }, + pgfsysanimkeyrepeatdur = { + arguments = {{meta = "seconds"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrepeatdur" + }, + pgfsysanimkeyrepeatevent = { + arguments = { + {meta = "id"}, + {meta = "type"}, + {meta = "repeat count"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrepeatevent" + }, + pgfsysanimkeyrepeatindefinite = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrepeatindefinite" + }, + pgfsysanimkeyrestartalways = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrestartalways" + }, + pgfsysanimkeyrestartnever = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrestartnever" + }, + pgfsysanimkeyrestartwhennotactive = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrestartwhennotactive" + }, + pgfsysanimkeyrotatealong = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrotatealong" + }, + pgfsysanimkeysnapshotstart = { + arguments = {{meta = "time offset"}}, + details = [[ +This command specifies that for the current animation the "moment `0s`" +of the timeline is at ⟨time offset⟩. Thus, it works like +`\pgfsysanimkeyoffset`, only the offset is now solely for the snapshot +timeline. It has no effect on the actual animation. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeysnapshotstart" + }, + pgfsysanimkeysyncbegin = { + arguments = { + {meta = "sync base id"}, + {meta = "type"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeysyncbegin" + }, + pgfsysanimkeysyncend = { + arguments = { + {meta = "sync base id"}, + {meta = "type"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeysyncend" + }, + pgfsysanimkeytime = { + arguments = { + {meta = "time"}, + {meta = "entry spline control x"}, + {meta = "entry spline control y"}, + {meta = "exit spline control x"}, + {meta = "exit spline control y"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeytime" + }, + pgfsysanimkeytipmarkers = { + arguments = {{meta = "start marker"}, {meta = "end marker"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeytipmarkers" + }, + pgfsysanimkeywhom = { + arguments = {{meta = "id"}, {meta = "type"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeywhom" + }, + pgfsysanimsnapshot = { + arguments = {{meta = "time"}}, + details = [[ +Use this command in a scope prior to calling any other commands +documented in this section concerning the configuration of animations. +In this case, all uses of `\pgfsysanimate` inside the TeX scope no +longer insert an animation into the output file. Instead, a "snapshot" +is inserted of what the animation "would like at time ⟨time⟩". For +instance, if an animation inserts a movement of an object by 4cm over a +time of 2s and you take a snapshot with $⟨time⟩ = 2\mathrm s$, you get a +picture in which the object is moved by 1cm. + +A lot of care has been taken to make the output produced by the snapshot +be as close as possible as what the animation really would look like at +time ⟨time⟩, but note the following restrictions: + +1. Interactive events of all kinds (like `click` or `mouseover`) make + little sense for snapshots, which are created once and for all + during the typesetting of the document. For this reason, all events + are ignored for snapshots (even sync bases, and `begin` and `end` + events, which might make some sense also in a snapshot setting). + + However, there is one command which helps you with "simulating" the + effect of events: + +2. The command `\pgfsysanimvalcurrent` cannot be used with snapshots + since PGF has no chance of computing the correct current value. You + always have to specify the start value explicitly. + +3. The computation of time splines (entry and exit splines) and the + accumulation of values after a large number of repeats may not be + numerically stable. + + + + \foreach \t in {0.5,1,1.5,2} { + \pgfsysanimsnapshot{\t} + \tikz { + \pgfidrefnextuse{\objid}{node} + \pgfsysanimkeywhom{\objid}{} + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalscalar{1} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalscalar{0} + \pgfsysanimate{opacity} + \node (node) [draw = blue, very thick, fill=blue!20, circle] {Hi}; + } + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimsnapshot" + }, + pgfsysanimsnapshotafter = { + arguments = {{meta = "time"}}, + details = [[ +Works like the previous command, only the "moment" that ⟨time⟩ refers to +is conceptually $⟨time⟩ + \epsilon$: When timeline specifies several +values for ⟨time⟩, this command will select the last value at ⟨time⟩, +while `\pgfsnapshot` will select the first value at ⟨time⟩. Similarly, +when a timeline ends at ⟨time⟩, `\pgfsnapshot` will select the last +value of the timeline while `\pgfsnapshotafter` will not apply the +animation any more. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimsnapshotafter" + }, + pgfsysanimvalcolorcmy = { + arguments = {{meta = "cyan"}, {meta = "magenta"}, {meta = "yellow"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalcolorcmy" + }, + pgfsysanimvalcolorcmyk = { + arguments = { + {meta = "cyan"}, + {meta = "magenta"}, + {meta = "yellow"}, + {meta = "black"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalcolorcmyk" + }, + pgfsysanimvalcolorgray = { + arguments = {{meta = "gray value"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalcolorgray" + }, + pgfsysanimvalcolorrgb = { + arguments = {{meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalcolorrgb" + }, + pgfsysanimvalcurrent = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalcurrent" + }, + pgfsysanimvaldash = { + arguments = {{meta = "pattern"}, {meta = "phase"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvaldash" + }, + pgfsysanimvaldimension = { + arguments = {{meta = "dimension"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvaldimension" + }, + pgfsysanimvalpath = { + arguments = {{meta = "low-level path construction commands"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalpath" + }, + pgfsysanimvalscalar = { + arguments = {{meta = "number"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalscalar" + }, + pgfsysanimvalscale = { + arguments = {{meta = "x scale"}, {meta = "y scale"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalscale" + }, + pgfsysanimvaltext = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvaltext" + }, + pgfsysanimvaltranslate = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvaltranslate" + }, + pgfsysanimvalviewbox = { + arguments = { + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalviewbox" + }, + pgfsysdriver = { + details = [[ +This macro should expand to the name of the driver to be used by +`pgfsys`. The default from `pgf.cfg` is `pgfsys-\Gin@driver`. This is +very likely to be correct if you are using LaTeX. For plain TeX, the +macro will be set to `pgfsys-pdftex.def` if `pdftex` is used and to +`pgfsys-dvips.def` otherwise. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysdriver" + }, + ["pgfsysprotocol@bufferedfalse"] = { + details = [[ +Turns off protocolling. Subsequent calls of `\pgfsysprotocol@literal` +directly insert their argument into the current `.pdf` or `.ps`. + +Note that if the current protocol is not empty when protocolling is +switched off, the next call to `\pgfsysprotocol@literal` will first +flush the current protocol, that is, insert it into the file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@bufferedfalse" + }, + ["pgfsysprotocol@bufferedtrue"] = { + details = [[ +Turns on protocolling. All subsequent calls of `\pgfsysprotocol@literal` +will append their argument to the current protocol. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@bufferedtrue" + }, + ["pgfsysprotocol@flushcurrentprotocol"] = { + details = [[ +First inserts the current protocol, then sets the current protocol to +the empty string. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@flushcurrentprotocol" + }, + ["pgfsysprotocol@getcurrentprotocol"] = { + arguments = {{meta = "macro name"}}, + details = [[ +Stores the current protocol in ⟨macro name⟩ for later use. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@getcurrentprotocol" + }, + ["pgfsysprotocol@invokecurrentprotocol"] = { + details = [[ +Inserts the text stored in the current protocol into the `.pdf` or +`.dvi` file. This does *not* change the current protocol. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@invokecurrentprotocol" + }, + ["pgfsysprotocol@literal"] = { + arguments = {{meta = "literal text"}}, + details = [[ +First calls `\pgfsysprotocol@literalbuffered` on ⟨literal text⟩. Then, +if protocolling is currently switched off, the ⟨literal text⟩ is passed +on to `\pgfsys@invoke`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@literal" + }, + ["pgfsysprotocol@literalbuffered"] = { + arguments = {{meta = "literal text"}}, + details = [[ +Adds the ⟨literal text⟩ to the current protocol, after it has been +"`\edef`ed". This command will always be protocolled. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@literalbuffered" + }, + ["pgfsysprotocol@setcurrentprotocol"] = { + arguments = {{meta = "macro name"}}, + details = [[ +Sets the current protocol to ⟨macro name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@setcurrentprotocol" + }, + ["pgfsyssoftpath@closepath"] = { + details = [[ +Appends a "close-path" segment to the current soft path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@closepath" + }, + ["pgfsyssoftpath@curveto"] = { + arguments = { + {meta = "a"}, + {meta = "b"}, + {meta = "c"}, + {meta = "d"}, + {meta = "x"}, + {meta = "y"} + }, + details = [[ +Appends a "curve-to" segment to the current soft path with controls +$(a,b)$ and $(c,d)$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@curveto" + }, + ["pgfsyssoftpath@flushcurrentpath"] = { + details = [[ +This command will invoke the current soft path and then set it to be +empty. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@flushcurrentpath" + }, + ["pgfsyssoftpath@getcurrentpath"] = { + arguments = {{meta = "macro name"}}, + details = [[ +This command will store the current soft path in ⟨macro name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@getcurrentpath" + }, + ["pgfsyssoftpath@invokecurrentpath"] = { + details = [[ +This command will turn the current soft path in a "hard" path. To do so, +it iterates over the soft path and calls an appropriate `\pgfsys@xxxx` +command for each element of the path. Note that the current soft path is +*not changed* by this command. Thus, in order to start a new soft path +after the old one has been invoked and is no longer needed, you need to +set the current soft path to be empty. This may seem strange, but it is +often useful to immediately use the last soft path again. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@invokecurrentpath" + }, + ["pgfsyssoftpath@lineto"] = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +Appends a "line-to" segment to the current soft path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@lineto" + }, + ["pgfsyssoftpath@moveto"] = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +This command appends a "move-to" segment to the current soft path. The +coordinates ⟨x⟩ and ⟨y⟩ are given as normal TeX dimensions. + +One way to draw a line: + + \pgfsyssoftpath@moveto{0pt}{0pt} + \pgfsyssoftpath@lineto{10pt}{10pt} + \pgfsyssoftpath@flushcurrentpath + \pgfsys@stroke +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@moveto" + }, + ["pgfsyssoftpath@rect"] = { + arguments = { + {meta = "lower left x"}, + {meta = "lower left y"}, + {meta = "width"}, + {meta = "height"} + }, + details = [[ +Appends a rectangle segment to the current soft path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@rect" + }, + ["pgfsyssoftpath@setcurrentpath"] = { + arguments = {{meta = "macro name"}}, + details = [[ +This command will set the current soft path to be the path stored in +⟨macro name⟩. This macro should store a path that has previously been +extracted using the `\pgfsyssoftpath@getcurrentpath` command and has +possibly been modified subsequently. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@setcurrentpath" + }, + pgftext = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "text"} + }, + details = [[ +This command will typeset ⟨text⟩ in normal TeX mode and insert the +resulting box into the `{pgfpicture}`. The bounding box of the graphic +will be updated so that all of the text box is inside. By default, the +text box is centered at the origin, but this can be changed either by +giving appropriate ⟨options⟩ or by applying an appropriate coordinate +transformation beforehand. + +The ⟨text⟩ may contain verbatim text. (In other words, the ⟨text⟩ +"argument" is not a normal argument, but is put in a box and some +`\aftergroup` hackery is used to find the end of the box.) + +PGF's current (high-level) coordinate transformation is synchronized +with the canvas transformation matrix temporarily when the text box is +inserted. The effect is that if there is currently a high-level rotation +of, say, 30 degrees, the ⟨text⟩ will also be rotated by thirty degrees. +If you do not want this effect, you have to (possibly temporarily) reset +the high-level transformation matrix. + +The ⟨options⟩ keys are used with the path `/pgf/text/`. The following +keys are defined for this path: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftext" + }, + pgftransformarcaxesattime = { + arguments = { + {meta = "time $t$"}, + {meta = "center"}, + {meta = "0-degree axis"}, + {meta = "90-degree axis"}, + {meta = "start angle"}, + {meta = "end angle"} + }, + details = [[ +Shifts coordinates by a specific point on an arc at a specific time, see +Section ?? once more. + +As for the previous commands, `\ifpgfslopedattime` decides whether an +additional rotation should be applied and `\ifpgfallowupsidedowattime` +is also considered. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpoint{2cm}{1cm}} + \pgfpatharcaxes{0}{60}{\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}} + \pgfusepath{stroke} + \pgfslopedattimetrue + \pgftransformarcaxesattime{.25} + {\pgfpoint{0cm}{1cm}} + {\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}} + {0}{60} + \pgftext{Hi!} + \end{tikzpicture} + +The value of `\ifpgfresetnontranslationsattime` is also taken into +account. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformarcaxesattime" + }, + pgftransformarrow = { + arguments = {{meta = "start"}, {meta = "end"}}, + details = [[ +Shifts coordinates to the end of the line going from ⟨start⟩ to ⟨end⟩ +with the correct rotation. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (3,1); + \pgftransformarrow{\pgfpointorigin}{\pgfpoint{3cm}{1cm}} + \pgftext{tip} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformarrow" + }, + pgftransformationadjustments = { + details = [[ +This command computes "adjustments" for the current transformation +matrix so that even when you install a transformation matrix that scales +everything by a certain factor, you can still draw something of "an +absolute size". Suppose for instance that you install a transformation +matrix that scales everything by a factor of 4 and you now wish to draw +a horizontal line of length 1cm. Then, if you do not reset the +transformation matrix, you can draw a line of logical length 2.5mm, +which will then get scaled to a line of 1cm. Things get more difficult +in case you scale things only, say, vertically. In this case, the +adjustment necessary for horizontal lines is different from the one +needed for vertical lines. + +This function computes two scaling factors, one for horizontal lines and +one for vertical lines, and stores them in the following macros: + +Note that the "right" way to draw a line of absolute length 1cm in a +transformed coordinate system is to first compute the start point and to +then reset the transformation matrix. The transformation adjustments +computed here are important only in situations where you cannot do this, +for instance when an `outer xsep` must be set. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformationadjustments" + }, + pgftransformcm = { + arguments = { + {meta = "a"}, + {meta = "b"}, + {meta = "c"}, + {meta = "d"}, + {meta = "point"} + }, + details = [[ +Applies the transformation matrix given by $a$, $b$, $c$, and $d$ and +the shift ⟨point⟩ to coordinates (in addition to any previous +transformations already in force). + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformcm{1}{1}{0}{1}{\pgfpoint{.25cm}{.25cm}} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformcm" + }, + pgftransformcurveattime = { + arguments = { + {meta = "time"}, + {meta = "start"}, + {meta = "first support"}, + {meta = "second support"}, + {meta = "end"} + }, + details = [[ +Shifts coordinates by a specific point on a curve at a specific time, +see Section ?? once more. + +As for the line-at-time transformation command, `\ifpgfslopedattime` +decides whether an additional rotation should be applied. Again, the +value of `\ifpgfallowupsidedowattime` is also considered. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) .. controls (0,2) and (1,2) .. (2,1); + \pgftransformcurveattime{.25}{\pgfpointorigin} + {\pgfpoint{0cm}{2cm}}{\pgfpoint{1cm}{2cm}}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) .. controls (0,2) and (1,2) .. (2,1); + \pgfslopedattimetrue + \pgftransformcurveattime{.25}{\pgfpointorigin} + {\pgfpoint{0cm}{2cm}}{\pgfpoint{1cm}{2cm}}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} + +The value of `\ifpgfresetnontranslationsattime` is also taken into +account. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformcurveattime" + }, + pgftransforminvert = { + details = [[ +Replaces the coordinate transformation matrix by a coordinate +transformation matrix that "exactly undoes the original transformation". +For example, if the original transformation was "scale by 2 and then +shift right by 1cm" the new one is "shift left by 1cm and then scale by +$1/2$". + +This command will produce an error if the determinant of the matrix is +too small, that is, if the matrix is near-singular. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformrotate{30} + \draw (0,0) -- (2,1) -- (1,0); + \pgftransforminvert + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransforminvert" + }, + pgftransformlineattime = { + arguments = {{meta = "time"}, {meta = "start"}, {meta = "end"}}, + details = [[ +Shifts coordinates by a specific point on a line at a specific time. The +point by which the coordinate is shifted is calculated by calling +`\pgfpointlineattime`, see Section ??. + +In addition to shifting the coordinate, a rotation *may* also be +applied. Whether this is the case depends on whether the TeX if +`\ifpgfslopedattime` is set to true or not. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1); + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1); + \pgfslopedattimetrue + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} + +If `\ifpgfslopedattime` is true, another TeX `\if` is important: +`\ifpgfallowupsidedowattime`. If this is false, PGF will ensure that the +rotation is done in such a way that text is never "upside down". + +There is another TeX `\if` that influences this command. If you set +`\ifpgfresetnontranslationattime` to true, then, between shifting the +coordinate and (possibly) rotating/sloping the coordinate, the command +`\pgftransformresetnontranslations` is called. See the description of +this command for details. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformscale{1.5} + \draw (0,0) -- (2,1); + \pgfslopedattimetrue + \pgfresetnontranslationattimefalse + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformscale{1.5} + \draw (0,0) -- (2,1); + \pgfslopedattimetrue + \pgfresetnontranslationattimetrue + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformlineattime" + }, + pgftransformnonlinear = { + arguments = {{meta = "transformation code"}}, + details = [[ +This command adds the ⟨transformation code⟩ to the list of non-linear +transformations currently in force. Thus, similar to linear coordinate +transformations, each additional call to this function adds another +transformation to the current TeX scope and the effect ends at the end +of the current scope. In practice, however, you typically will not have +more than one active nonlinear transformation. + +The job of the ⟨transformation code⟩ is to map a point $p$ given in the +registers `\pgf@x` and `\pgf@y` to a new coordinate $f(p)$, which should +be returned in `\pgf@x` and `\pgf@y` as well. As an example, suppose we +wish to install polar coordinates as the nonlinear transformation. For +this, we need a bit of code: + + \def\polartransformation{% + % \pgf@x will contain the radius + % \pgf@y will contain the distance + \pgfmathsincos@{\pgf@sys@tonumber\pgf@x}% + % pgfmathresultx is now the cosine of radius and + % pgfmathresulty is the sine of radius + \pgf@x=\pgfmathresultx\pgf@y% + \pgf@y=\pgfmathresulty\pgf@y% + } + +(In case you wonder why you cannot just call `\pgfpointpolar` at this +point: You can, but this function internally uses `\pgf@x` and `\pgf@y` +in complicated ways, so you would first have to safe them so some other +registers. Also, the above is faster.) + +If we were to call this function again, we would get something funny +like "polar-polar coordinates", so let's not do this. Let us instead +have a look at the effect this call has: Once a nonlinear transformation +is installed, all subsequent path constructions are affected by this +transformation. In particular, a normal grid now becomes the typical +"polar grid". + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + % Start nonlinear transformation + \pgftransformnonlinear{\polartransformation}% see above + + % Draw something with this transformation in force + \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformnonlinear" + }, + pgftransformreset = { + details = [[ +Resets the coordinate transformation matrix to the identity matrix. +Thus, once this command is given no transformations are applied till the +end of the scope. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformrotate{30} + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformreset + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformreset" + }, + pgftransformresetnontranslations = { + details = [[ +This command sets the $a$, $b$, $c$, and $d$ part of the coordinate +transformation matrix to $a=1$, $b=0$, $c=0$, and $d=1$. However, the +current shifting of the matrix is not modified. + +The effect of this command is that any rotation/scaling/slanting is +undone in the current TeX group, but the origin is not "moved back". + +This command is mostly useful directly before a `\pgftext` command to +ensure that the text is not scaled or rotated. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformscale{2} + \pgftransformrotate{30} + \pgftransformxshift{1cm} + {\color{red}\pgftext{rotated}} + \pgftransformresetnontranslations + \pgftext{shifted only} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformresetnontranslations" + }, + pgftransformrotate = { + arguments = {{meta = "angles"}}, + details = [[ +Rotates coordinates counterclockwise by ⟨angles⟩ given in degrees. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformrotate{30} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformrotate" + }, + pgftransformscale = { + arguments = {{meta = "factor"}}, + details = [[ +Scales coordinates by ⟨factor⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformscale{.75} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformscale" + }, + pgftransformshift = { + arguments = {{meta = "point"}}, + details = [[ +Shifts coordinates by ⟨point⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformshift{\pgfpoint{1cm}{1cm}} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformshift" + }, + pgftransformtriangle = { + arguments = {{meta = "a"}, {meta = "b"}, {meta = "c"}}, + details = [[ +This command transforms the coordinate system in such a way that the +triangle given by the points ⟨a⟩, ⟨b⟩ and ⟨c⟩ lies at the coordinates +$(0,0)$, $(1\mathrm{pt},0\mathrm{pt})$ and +$(0\mathrm{pt},1\mathrm{pt})$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformtriangle + {\pgfpoint{1cm}{0cm}} + {\pgfpoint{0cm}{2cm}} + {\pgfpoint{3cm}{1cm}} + + \draw (0,0) -- (1pt,0pt) -- (0pt,1pt) -- cycle; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformtriangle" + }, + pgftransformxscale = { + arguments = {{meta = "factor"}}, + details = [[ +Scales coordinates by ⟨factor⟩ in the $x$-direction. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformxscale{.75} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformxscale" + }, + pgftransformxshift = { + arguments = {{meta = "dimensions"}}, + details = [[ +Shifts coordinates by ⟨dimension⟩ along the $x$-axis. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformxshift{.5cm} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformxshift" + }, + pgftransformxslant = { + arguments = {{meta = "factor"}}, + details = [[ +Slants coordinates by ⟨factor⟩ in the $x$-direction. Here, a factor of +`1` means $45^\circ$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformxslant{.5} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformxslant" + }, + pgftransformyscale = { + arguments = {{meta = "factor"}}, + details = [[ +Like `\pgftransformxscale`, only for the $y$-axis. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformyscale" + }, + pgftransformyshift = { + arguments = {{meta = "dimensions"}}, + details = [[ +Like `\pgftransformxshift`, only for the $y$-axis. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformyshift" + }, + pgftransformyslant = { + arguments = {{meta = "factor"}}, + details = [[ +Slants coordinates by ⟨factor⟩ in the $y$-direction. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformyslant{-1} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformyslant" + }, + pgfuseid = { + arguments = {{meta = "name"}}, + details = [[ +The ⟨name⟩ is a string by which the object will be referenced (see +`\pgfidrefnextuse`). The next time a graphic object is created in the +current TeX scope, the name will be attached to it (actually, it will +get a system layer identifier attached to it that is automatically +created using `\pgfsys@new@id`, the ⟨name⟩ is bound to that identifier +and it can be retrieved using `\pgfidrefnextuse`). This holds true only +for the next object: If a second object is created, it will not get the +name attached to it. This does not mean, however, that you cannot attach +the same name to different objects; you just need to call `\pgfuseid` +again before each object. + +Besides the ⟨name⟩ (or, more precisely, besides the system layer +identifier is refers to), the current *identifier type* is also +important: Actually, a graphic object is not referenced by a system +layer identifier, but by the combination of the identifier and a type. +You can use the following commands for modifying the type used for the +creation of objects: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfuseid" + }, + pgfuseimage = { + arguments = {{meta = "image name"}}, + details = [[ +Inserts a previously declared image into the *normal text*. If you wish +to use it in a `{pgfpicture}` environment, you must put a `\pgftext` +around it. + +If the macro `\pgfalternateextension` expands to some nonempty +⟨alternate extension⟩, PGF will first try to use the image named ⟨image +name⟩`.`⟨alternate extension⟩. If this image is not defined, PGF will +next check whether ⟨alternate extension⟩ contains a `!` character. If +so, everything up to this exclamation mark and including it is deleted +from ⟨alternate extension⟩ and the PGF again tries to use the image +⟨image name⟩`.`⟨alternate extension⟩. This is repeated until ⟨alternate +extension⟩ no longer contains a `!`. Then the original image is used. + +The `xxcolor` package sets the alternate extension to the current color +mixin. + + \pgfdeclareimage[interpolate=true,width=1cm,height=1cm] + {image1}{brave-gnu-world-logo} + \pgfdeclareimage[interpolate=true,width=1cm]{image2}{brave-gnu-world-logo} + \pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo} + \begin{pgfpicture} + \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}} + \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}} + \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}} + + \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} + \end{pgfpicture} + +The following example demonstrates the effect of using `\pgfuseimage` +inside a colormixin environment. + + \pgfdeclareimage[interpolate=true,width=1cm,height=1cm] + {image1.!25!white}{brave-gnu-world-logo.25} + \pgfdeclareimage[interpolate=true,width=1cm] + {image2.25!white}{brave-gnu-world-logo.25} + \pgfdeclareimage[interpolate=true,height=1cm] + {image3.white}{brave-gnu-world-logo.25} + \begin{colormixin}{25!white} + \begin{pgfpicture} + \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}} + \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}} + \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}} + + \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} + \end{pgfpicture} + \end{colormixin} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfuseimage" + }, + pgfusepath = { + arguments = {{meta = "actions"}}, + details = [[ +Applies the given ⟨actions⟩ to the current path. Afterwards, the current +path is (globally) empty. The following actions are possible: + +- `fill` fills the path. See Section ?? for further details. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{fill} + \end{pgfpicture} + +- `stroke` strokes the path. See Section ?? for further details. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \end{pgfpicture} + +- `draw` has the same effect as `stroke`. + +- `clip` clips all subsequent drawings against the path. Always + suppresses arrow tips. See Section ?? for further details. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke,clip} + \pgfpathcircle{\pgfpoint{1cm}{1cm}}{0.5cm} + \pgfusepath{fill} + \end{pgfpicture} + +- `discard` discards the path, that is, it is not used at all. Giving + this option (alone) has the same effect as giving an empty options + list. + +When more than one of the first three actions are given, they are +applied in the above ordering, regardless of their ordering in +⟨actions⟩. Thus, `{stroke,fill}` and `{fill,stroke}` have the same +effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusepath" + }, + pgfusepathqclip = { + details = [[ +Clips all subsequent drawings against the current path. The path is not +processed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusepathqclip" + }, + pgfusepathqfill = { + details = [[ +Fills the path without further ado. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusepathqfill" + }, + pgfusepathqfillstroke = { + details = [[ +Fills and then strokes the path without further ado. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusepathqfillstroke" + }, + pgfusepathqstroke = { + details = [[ +Strokes the path without further ado. No arrows are drawn, no corners +are arced. + + \begin{pgfpicture} + \pgfpathqcircle{5pt} + \pgfusepathqstroke + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusepathqstroke" + }, + pgfuseplotmark = { + arguments = {{meta = "plot mark name"}}, + details = [[ +Draws the given ⟨plot mark name⟩ at the origin. The ⟨plot mark name⟩ +must have been previously declared using `\pgfdeclareplotmark`. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfuseplotmark{pentagon}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfuseplotmark" + }, + pgfuseshading = { + arguments = {{meta = "shading name"}}, + details = [[ +Inserts a previously declared shading into the text. If you wish to use +it in a `pgfpicture` environment, you should put a `\pgftext` around it. + + \begin{pgfpicture} + \pgfdeclareverticalshading{myshadingD} + {20pt}{color(0pt)=(red); color(20pt)=(blue)} + \pgftext[at=\pgfpoint{1cm}{0cm}] {\pgfuseshading{myshadingD}} + \pgftext[at=\pgfpoint{2cm}{0.5cm}]{\pgfuseshading{myshadingD}} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfuseshading" + }, + pgfusetype = { + arguments = {{meta = "type"}}, + details = [[ +Sets the type used for the referencing of graphic objects for the +current scope to ⟨type⟩ or, if ⟨type⟩ starts with a dot, appends ⟨type⟩ +to the current type. + +You use this command with compound graphic objects: Before each part of +a graphic object, set the type to an appropriate value. Now, if the +object is named using `\pgfuseid`, you can later on access all parts of +the compound object using the combination of the ⟨name⟩ used with +`\pgfuseid` and the type of the part. + +As an example, this system is used to give you access to the different +parts of a node: When use say `\pgfuseid{mynode}` and then create a +node, you can use `mynode` with the empty type to reference the graphics +scope that encompasses the whole node, but also `mynode` together with +the type `background` to access the background path of the node. + +In detail, PGF uses this command to set the following types: + +- Inside the command `\pgfviewboxscope`, the type `.view` is used for + the view object. + +- Inside the command `\pgfmultipartnode`, the type + `.behind background` is used for the scope of drawings behind the + background. Similarly, `.before background` and `.behind foreground` + and finally `.before foreground` are used with the respective parts + of a node. + +- Also inside a node, `.background` and `.foreground` are used as + types of the background and foreground paths, respectively. + +- Finally, inside a node, for each text part, the text part's name is + used as a type (so `.text` is used for the main part). + +In addition, TikZ uses this command in the following situations: + +- The type `.path` is used with a named path (named using the `name` + key). This is the graphic object you need to reference when you wish + to morph a path. + +- The type `.path picture` is used with the scope of the optional path + picture. + +- The type `.path fill` is used with the path used for filling. This + is not the same as the normal path in case the path is filled and + patterned, for instance. + +- The type `.path shade` is used with the path used for shading a + path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusetype" + }, + pgfverticaltransformationadjustment = { + details = [[ +$1/\\texttt{\textbackslash mathit\{transform\}(0,1)\textbackslash }_2$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfverticaltransformationadjustment" + }, + pgfwarning = { + arguments = {{meta = "message"}}, + details = [[ +Prints the ⟨message⟩ on the output, but does not interrupt the +processing. In LaTeX, this will be done using `\PackageWarning`, +otherwise a write to stream $17$ is used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfwarning" + }, + usepgflibrary = { + arguments = {{meta = "list of libraries"}}, + details = [[ +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. If you try to load a library a +second time, nothing will happen. + +`\usepgflibrary{arrows}` + +This command causes the file `pgflibrary`⟨library⟩`.code.tex` to be +loaded for each ⟨library⟩ in the ⟨list of libraries⟩. This means that in +order to write your own library file, place a file of the appropriate +name somewhere where TeX can find it. LaTeX, plain TeX, and ConTeXt +users can then use your library. + +You should also consider adding a TikZ library that simply includes your +PGF library. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/usepgflibrary" + }, + usepgfmodule = { + arguments = {{meta = "module names"}}, + details = [[ +Once the core has been loaded, you can use this command to load further +modules. The modules in the ⟨module names⟩ list should be separated by +commas. Instead of curly braces, you can also use square brackets, which +is something ConTeXt users will like. If you try to load a module a +second time, nothing will happen. + +`\usepgfmodule{matrix,shapes}` + +What this command does is to load the file +`pgfmodule`⟨module⟩`.code.tex` for each ⟨module⟩ in the list of ⟨module +names⟩. Thus, to write your own module, all you need to do is to place a +file of the appropriate name somewhere TeX can find it. LaTeX, plain +TeX, and ConTeXt users can then use your library. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/usepgfmodule" + } +} +keys = { + pgf = { + ["/pgfparser/silent"] = { + details = [[ +If `true` then no error will be thrown when a letter is parsed for which +no action is specified, silently ignoring it. This holds true for every +parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgfparser/silent", + meta = "⟨boolean⟩" + }, + ["/pgfparser/status"] = { + details = [[ +If `true` every parser prints a status message for every action +executed. This might help in debugging and understanding what the parser +does. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgfparser/status", + meta = "⟨boolean⟩" + }, + ["/pgfparser/⟨parser name⟩/silent"] = { + details = [[ +If `true` the parser ⟨parser name⟩ will silently ignore undefined +letters. This is an individual equivalent of `/pgfparser/silent` for +each defined parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgfparser/⟨parser:name⟩/silent", + meta = "⟨boolean⟩" + }, + ["and gate IEC symbol"] = { + details = [[ +Set the symbol for the `and gate`. Note that if the node is filled, this +color will be used for the symbol, making it invisible, so it will be +necessary set ⟨text⟩ to something like `\color{black}\char‘\& `. +Alternatively, the `logic gate IEC symbol color` key can be used to set +the color of all symbols simultaneously. + +In TikZ, when the `use IEC style logic gates` key has been used, this +key can be replaced by `and gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/and:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["animate/events/click"] = { + details = [[ +This is a shorthand for `event=click`. This event gets triggered when +the user clicks on the triggering object with a mouse (or something +equivalent). + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {click}} + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animate/events/click" + }, + ["animation/along"] = { + details = [[ +This key must be used with `motion` attribute to specify a path along +which the transformation matrix will be "moved" (that is, a shift +transformation will be added to the different points on the path). + +The values passed to the `entry` key specify fractions of the distance +along the ⟨path⟩. That means, when you provide a value of `0`, you +reference the start point of the path, a value of `1` references the end +of the path and `0.5` referenced the point halfway along the path. + + \tikz [very thick] { + \pgfanimateattribute{motion}{ + whom = node, begin on = {click}, + along = \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{0mm}{5mm}}, + entry = {0s}{0}, entry = {1s}{0.5}, entry = {2s}{0.25}, entry={3s}{1} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/along", + meta = "⟨path⟩" + }, + ["animation/arrows"] = { + details = [[ +This key specifies arrow tips during the animation of the path. The +syntax for the arrow tips is the same syntax as the `\pgfsetarrow` +command or TikZ's `arrows` key. The specified start and end arrow tips +are rendered as "markers", which are added to the path *only* during the +animation. The markers are rotated along with the path in exactly the +same way as normal arrow tips would be. To be precise, the rules used +for the computation of where arrow tips go and in which direction they +head is not always the same for "static" arrow tips (arrow tips added to +a normal path) and the "dynamic" arrow tips based on markers; namely +when the paths are very short or closed. For this reason, you should add +arrow tips to animated paths only when the paths are "nice and simple" +in the sense that they consist of a single segment whose ends are +reasonably long. + +In addition to adding the arrow tips to the path during the animation, +the path gets shortened as necessary to compensate for the extend of the +arrow tips. However, for this to work, the arrow tips have to be +specified before path values are specified (since the shortening is done +immediately when a path value is parsed). + + \tikz { + \pgfanimateattribute{path}{ + whom = p.path, begin on = {click, of next=node}, arrows = ->, + entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}}}, + entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}}}} + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + \draw [very thick, blue, name=p] (1,0.5) -- (2,0.5); + } + +Note that the markers that visualize the arrow tips are rendered only +once per animation. In consequence, "bending" arrow tips cannot be +rendered correctly: As a path "morphs" a bend arrow tip needs not only +to rotate along, but must actually "bend along", which is not supported +(neither by PGF nor by SVG). + +As pointed out earlier, an animated path cannot have "static" arrow +tips. However, when you specify a `base` value, which is the path used +whenever there is no active animation, *will* use the arrow tips. As a +result, you can use this to animate a path with an arrow tip: + + \tikz { + \pgfanimateattribute{path}{ + whom = p.path, begin on = {click, of next=node}, arrows = ->, + base = {\pgfpathmoveto{\pgfpoint{1cm}{5mm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}}}, + entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}}}, + entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}}}} + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + \draw [very thick, blue, name=p]; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/arrows", + meta = "⟨start tip spec⟩-⟨end tip spec⟩" + }, + ["animation/begin"] = { + details = [[ +This key specifies when the "moment `0s`" should be relative to the +moment when the current graphic is first displayed. You can use this key +multiple times, in this case the timeline is restarted for each of the +times specified (if it is already running, it will be reset). If no +`begin` key is given at all, the effect is the same as if `begin=0s` had +been specified. + +It is permissible to set ⟨time⟩ to a negative value. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/begin", + meta = "⟨time⟩" + }, + ["animation/begin on"] = { + details = [[ +Has the same effect as `/tikz/animate/option/begin on`, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/begin:on", + meta = "⟨options⟩" + }, + ["animation/end"] = { + details = [[ +This key will truncate the timeline so that it ends ⟨time⟩ after the +display of the graphic, provided the timeline begins before the +specified end time. For instance, if you specify a timeline starting at +2 s and ending at 5 s and you set `begin` to 1 s and `end` to 4 s, the +timeline will run, relative to the moment when the graphic is displayed +from 3 s to 4 s. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin = 2s, end = 4s, + entry = {1s}{0}, entry = {2s}{90}, entry = {3s}{180}, entry = {4s}{270} } + \node (node) [fill = blue!20, draw = blue, circle] {Turn after 3s!}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/end", + meta = "⟨time⟩" + }, + ["animation/end on"] = { + details = [[ +Works exactly like `begin on`, one possible end of the timeline is +specified using the ⟨options⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/end:on", + meta = "⟨options⟩" + }, + ["animation/entry"] = { + details = [[ +You use this key repeatedly to specify the different values that the +⟨attribute⟩ should have over time. At the ⟨time⟩ specified, the +⟨attribute⟩ will have the value specified as ⟨value⟩: + + \tikz { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, + entry = {0s}{0}, entry = {1s}{90}, entry = {1.1s}{45}, entry = {2s}{90} + } + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } + +You need to call `entry` once for each time in the timeline for which +you want to specify a ⟨value⟩ explicitly. Between these times, the +values get interpolated (see below for details). You need to specify the +⟨time⟩s in non-decreasing order (it is permissible and sometimes also +necessary to specify the same time twice, namely to create a "jump" of +the value of some attribute). + +The ⟨time⟩ is parsed using the command `\pgfparsetime` described later. + +**Start and end of the timeline.** The first and last times of the +timeline are a bit special: The timeline starts on the first time and +the duration of the timeline is the difference between the first and +last time. "Starting" on the start time actually means that any +beginnings (see the `begin` and `end` keys) get offset by the start +time; similarly end times are offset by this value. + +**Syntax of the values.** The syntax of the ⟨value⟩ varies according to +the type of the ⟨attribute⟩. In detail, these are: + + ----------- ---------------------------------------------------------------- + *Type* *Syntax* + color Standard color syntax like `red` or `black!10` + scalar A value parsed using `\pgfmathparse` + dimension A dimension parsed using `\pgfmathparse` + path A sequence of path construction commands + softpath A sequence of soft path construction commands + scaling A scalar value or a pair of scalar values separated by a comma + point A PGF-point like `\pgfpoint{1cm}{5mm}` + viewbox Two PGF-points + boolean `true` or `false` + ----------- ---------------------------------------------------------------- + +**Interpolation between key times.** You use the `entry` key repeatedly, +namely once for each "key time", which is a time point for which you +specify the value of the attribute explicitly. Between these key times, +the attribute's value is interpolated. Normally, this is just a linear +interpolation, but you can influence this using the following keys, see +Section ?? for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/entry", + meta = "{time}{value}" + }, + ["animation/events/begin"] = { + details = [[ +Shorthand for `event=begin`. The "begin" refers to the beginning of +another animation, namely the one referenced by `of` or `of whom`. This +means that the current animation will begin when some other animation +begins. + + \tikz \node [animate = { + myself:rotate = { 0s="0", 2s="90", begin on = {begin, of next=anim}}, + myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim} + }, + fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/begin" + }, + ["animation/events/delay"] = { + details = [[ +Specifies that the timeline should not start with the event, but, +rather, be delayed by ⟨time⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/delay", + meta = "⟨time⟩" + }, + ["animation/events/end"] = { + details = [[ +Shorthand for `event=end`. Again, the "end" refers to the end of another +animation, namely the one referenced by `of` or `of whom`. This means +that the current animation will *begin* when some other animation +*ends*. + + \tikz \node [animate = { + myself:rotate = { 0s="0", 2s="90", begin on = {end, of next=anim}}, + myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim } + }, + fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/end" + }, + ["animation/events/event"] = { + details = [[ +Specifies the name of the event whose occurrence should start the +timeline. Which events are supported depends on the device on which the +animation is displayed, the output format (SVG or some other format), +and the setup of scripts, but here is a list of events supported by +"plain SVG": `click`, `focusin`, `focusout`, `mousedown`, `mouseup`, +`mouseover`, `mousemove`, `mouseout`, `begin`, `end`. However, the +following keys make using these events simpler: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/event", + meta = "⟨event name⟩" + }, + ["animation/events/focus in"] = { + details = [[ +This is a shorthand for `event=focusin`. This event gets triggered when +the graphic object gets the focus (this usually makes sense only for +text input fields). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/focus:in" + }, + ["animation/events/focus out"] = { + details = [[ +This is a shorthand for `event=focusout`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/focus:out" + }, + ["animation/events/key"] = { + details = [[ +The event is triggered when the keyboard key ⟨key⟩ has been pressed. For +security reasons, a viewer may suppress this. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/key", + meta = "⟨key⟩" + }, + ["animation/events/mouse down"] = { + details = [[ +Shorthand for `event=mousedown`. The event gets triggered when the user +presses a mouse button down on the object. + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse down}} + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/mouse:down" + }, + ["animation/events/mouse move"] = { + details = [[ +Shorthand for `event=mousemove`. The event gets triggered lots of times, +namely each time the mouse moves while being "over" the object. + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse move} } + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/mouse:move" + }, + ["animation/events/mouse out"] = { + details = [[ +Shorthand for `event=mouseout`. The opposite of `mouse over`: triggered +when the mouse leaves the object. + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse out} } + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/mouse:out" + }, + ["animation/events/mouse over"] = { + details = [[ +Shorthand for `event=mouseover`. The event gets triggered the moment the +mouse cursor moves over the object. + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse over} } + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/mouse:over" + }, + ["animation/events/mouse up"] = { + details = [[ +Shorthand for `event=mouseup` and gets triggered, of course, when a +pressed button is released on the object. + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse up} } + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/mouse:up" + }, + ["animation/events/of"] = { + details = [[ +This specifies a graphic object id in the same way as the `whom` key, +also with an optional ⟨type⟩. This is the object that "causes" the event +to happen. + +Unlike the `whom` key, which always refers to a not-yet-existing object, +this key always refers to an already existing object, namely to the most +recent use of the ⟨id⟩. In the following example, the referenced object +is the node with the label `2` since it is the most recently referenced +node with ⟨id⟩ `X`. + + \tikz [very thick] { + \node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1}; + \node (X) at (1,0.4) [fill = orange!20, draw = orange, circle] {2}; + \node (node) :rotate = {0s="0", 2s="90", begin on = {click, of = X}} + [fill = red!20, draw = red, rectangle] {Anim}; + \node (X) at (1,-0.4) [fill = blue!20, draw = blue, circle] {3}; + \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/of", + meta = "⟨id⟩.⟨type⟩" + }, + ["animation/events/of next"] = { + details = [[ +This key works like the `of` key, only it refers to a future (actually, +the next) object with the given ⟨id⟩, not to a previous one. This, in +the next example, the referenced node is the one with label `3`. + + \tikz [very thick] { + \node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1}; + \node (X) at (1,0.4) [fill = blue!20, draw = blue, circle] {2}; + \node (node) :rotate = { + 0s="0", 2s="90", begin on = {click, of next = X}} + [fill = red!20, draw = red, rectangle] {Anim}; + \node (X) at (1,-0.4) [fill = orange!20, draw = orange, circle] {3}; + \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/of:next", + meta = "⟨id⟩.⟨type⟩" + }, + ["animation/events/repeat"] = { + details = [[ +The event is triggered when a repeating animation has been repeated +⟨number⟩ times. + + \tikz + \node [animate = { myself: = { + :rotate = { 0s="0", 2s="90", begin on = {repeat = 2, of next = anim }, + begin snapshot = 2 }, + :xshift = { 0s="0mm", 2s="5mm", begin on=click, name=anim, repeats=4 }}}, + fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/repeat", + meta = "⟨number⟩" + }, + ["animation/freeze at end"] = { + details = [[ +When set to `true`, whenever a timeline ends (either because the last +time of timeline has been reached or because an `end` or `end of` key +have ended it prematurely), the last value the attribute had because of +the animation "stays put". When set to `false`, which is the initial +value, once an animation ends, its effect will be removed "as if it +never happened". + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, freeze at end = false, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Here!}; } + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, freeze at end, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Here!}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/freeze:at:end", + meta = "⟨true or false⟩" + }, + ["animation/name"] = { + details = [[ +Assigns a name to the animation by which it can be referenced using the +`of` and `of next` keys in another animation. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {end, of next = my move animation, delay = 1s}, + entry = {0s}{0}, entry = {2s}{90}, begin snapshot = 3s, } + \pgfanimateattribute{translate}{ + name = my move animation, whom = node, begin on = {click}, + entry = {0s}{\pgfpointorigin}, entry = {2s}{\pgfpoint{0cm}{-5mm}} } + \node (node) [fill = blue!20, draw = blue, circle] {Here!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/name", + meta = "⟨name⟩" + }, + ["animation/origin"] = { + details = [[ +An animation of the canvas transformation is added to all other +transformations from surrounding or interior scopes. This means that, in +particular, the origin of a canvas transformation is, by default, the +origin of the canvas of the scope surrounding the transformation object. + +For some canvas animations, like a rotation or a scaling, you will +typically wish to use a different origin (like the center of an object +that is to be rotated or scaled). You can achieve this effect by +surrounding the object by a scope that shifts the canvas to the desired +origin, followed by a scope whose transformation matrix you animate, +followed by a scope that shifts back the canvas. + +The `origin` key simplifies this process by allowing you to specify the +origin of the transformation directly. Internally, however, all this key +does is to create the above-mentioned scopes with the necessary shifts. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, + origin = \pgfpoint{-5mm}{0mm}, entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/origin", + meta = "⟨pgf point⟩" + }, + ["animation/repeat"] = { + details = [[ +This is an alias for `repeats`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/repeat", + meta = "⟨specification⟩" + }, + ["animation/repeats"] = { + details = [[ +Use this key to specify that the timeline animation should repeat at the +end. The ⟨specification⟩ must consist of two parts, each of which may be +empty. The first part is one of the following: + +- Empty, in which case the timeline repeats forever. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, repeats, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } + +- A ⟨number⟩ (like `2` or `3.25`), in which case the timeline repeats + ⟨number⟩ times. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, repeats = 1.75, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } + +- The text "`for` ⟨time⟩" (like `for 2s` or `for 300ms`), in which + case the timeline repeats however often necessary so that it stops + exactly after ⟨time⟩. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, repeats = for 3.5s, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } + +The second part of the specification must be one of the following: + +- Empty, in which case each time the timeline is restarted, the + attribute's value undergoes the same series of values it did + previously. + +- The text `accumulating`. This has the effect that each time the + timeline is restarted, the attribute values specified by the + timeline are *added* to the value from the previous iteration(s). A + typical example is an animation that shifts a scope by, say, 1 cm + over a time of 1 s. Now, if you repeat this five times, normally the + scope will shift 1 cm for 1 s then "jump back", shift again, jump + back, and so on for five times. In contrast, when the repeats are + accumulating, the scope will move by 5 cm over 5 s in total. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, repeats = accumulating, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, repeats = 2 accumulating, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/repeats", + meta = "⟨specification⟩" + }, + ["animation/restart"] = { + details = [[ +Has the same effect as `/tikz/animate/option/restart`, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/restart", + meta = "⟨choice⟩" + }, + ["animation/rotate along"] = { + details = [[ +When set to `true`, the `along` key additionally adds a rotation that +varies in such a way that a tangent to the path always points right. + + \tikz [very thick] { + \pgfanimateattribute{motion}{ + whom = node, begin on = {click}, + rotate along = true, + along = \pgfpathmoveto {\pgfpointorigin} + \pgfpathcurveto{\pgfpoint{5mm}{0cm}}{\pgfpoint{5mm}{0cm}} + {\pgfpoint{5mm}{5mm}}, + entry = {0s}{0}, entry = {2s}{1} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/rotate:along", + meta = "⟨Boolean⟩" + }, + ["animation/shorten <"] = { + details = [[ +Works like `shorten >`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/shorten:<", + meta = "⟨dimension⟩" + }, + ["animation/shorten >"] = { + details = [[ +Just like the normal TikZ key `shorten >`, this key specifies an extra +shortening of to-be-animated paths. Whenever a path is parsed as a value +for a path animation, it gets shortened at the end by the ⟨dimension⟩ +(and, additionally, by the length of the attached arrow tip). Just like +the `arrows` key, this key must be given before the path entries are +specified. + + \tikz { + \pgfanimateattribute{path}{ + whom = p.path, begin on = {click, of next=node}, arrows = ->, + shorten > = 2mm, + base = {\pgfpathmoveto{\pgfpoint{1cm}{5mm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}}}, + entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}}}, + entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}}}} + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + \draw (0.9,-0.1) grid (2.1,1.1); + \draw [help lines] (0.9,-0.1) grid[step=1mm] (2.1,1.1); + \draw [very thick, blue, name=p]; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/shorten:>", + meta = "⟨dimension⟩" + }, + ["animation/whom"] = { + details = [[ +You *must* use this key once which each call of the +`\pgfanimateattribute` command. The ⟨id⟩ and the optional ⟨type⟩ (which +is whatever follows the first dot) will be passed to `\pgfidrefnextuse`, +see that command for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/whom", + meta = "⟨id⟩.⟨type⟩" + }, + ["animations/entry control"] = { + details = [[ +Works like `exit control`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animations/entry:control", + meta = "{time fraction}{value fraction}" + }, + ["animations/exit control"] = { + details = [[ +Same as `/tikz/animate/options/exit control`. + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \pgfanimateattribute{translate}{ + whom = node, begin on = {click}, + exit control={1}{0}, + entry = {0s}{\pgfpointorigin}, + linear, % revert to default + entry = {1s}{\pgfpoint{0cm}{-5mm}}, + entry control={0}{1}, + entry = {2s}{\pgfpoint{0cm}{-10mm}} } + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animations/exit:control", + meta = "{time fraction}{value fraction}" + }, + ["animations/jump"] = { + details = [[ +Same as `/tikz/animate/options/jump`. + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \pgfanimateattribute{translate}{ + whom = node, begin on = {click}, + entry = {0s}{\pgfpointorigin}, + jump, + entry = {1s}{\pgfpoint{0cm}{-1cm}}, + linear, + entry = {2s}{\pgfpoint{0cm}{-2cm}} } + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animations/jump" + }, + ["animations/linear"] = { + details = [[ +A shorthand for `exit control={0}{0}, entry control={1}{1}`. This will +(re)install a linear curve. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animations/linear" + }, + ["animations/stay"] = { + details = [[ +Same as `/tikz/animate/options/stay`. + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \pgfanimateattribute{translate}{ + whom = node, begin on = {click}, + entry = {0s}{\pgfpointorigin}, + stay, + entry = {1s}{\pgfpoint{0cm}{-5mm}}, + linear, + entry = {2s}{\pgfpoint{0cm}{-10mm}}, + entry = {3s}{\pgfpoint{0cm}{-15mm}} } + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animations/stay" + }, + ["arrow box arrows"] = { + details = [[ +Sets the distance that all arrows extend from the node. The +specification in ⟨list⟩ consists of the four compass points `north`, +`south`, `east` or `west`, separated by commas (so the list must be +contained within braces). The distances can be specified after each side +separated by a colon (e.g., `north:1cm`, or `west:5cm from center`). If +an item specifies no distance, the most recently specified distance will +be used (at the start of the list this is `0cm`, so the first item in +the list should specify a distance). Any sides not specified will not be +drawn with an arrow. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:arrows", + meta = "{⟨list⟩}" + }, + ["arrow box east arrow"] = { + details = [[ +Sets the distance the east arrow extends from the node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:east:arrow", + meta = "⟨distance⟩" + }, + ["arrow box head extend"] = { + details = [[ +Sets the distance the arrow head extends away from the shaft of the +arrow. This applies to all arrows. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:head:extend", + meta = "⟨length⟩" + }, + ["arrow box head indent"] = { + details = [[ +Moves the point where the arrow head joins the shaft of the arrow +*towards* the arrow tip. This applies to all arrows. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:head:indent", + meta = "⟨length⟩" + }, + ["arrow box north arrow"] = { + details = [[ +Sets the distance the north arrow extends from the node. By default this +is from the border of the shape, but by using the additional keyword +`from center`, the distance will be measured from the center of the +shape. If ⟨distance⟩ is `0pt` or a negative distance, the arrow will not +be drawn. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:north:arrow", + meta = "⟨distance⟩" + }, + ["arrow box shaft width"] = { + details = [[ +Sets the width of the shaft of all arrows. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:shaft:width", + meta = "⟨length⟩" + }, + ["arrow box south arrow"] = { + details = [[ +Sets the distance the south arrow extends from the node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:south:arrow", + meta = "⟨distance⟩" + }, + ["arrow box tip angle"] = { + details = [[ +Sets the angle at the arrow tip for all four arrows. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:tip:angle", + meta = "⟨angle⟩" + }, + ["arrow box west arrow"] = { + details = [[ +Sets the distance the west arrow extends from the node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:west:arrow", + meta = "⟨distance⟩" + }, + ["arrow keys/angle"] = { + details = [[ +This key sets the `length` and the `width` of an arrow tip at the same +time. The length will be the cosine of ⟨angle⟩, while the width will be +twice the sine of half the ⟨angle⟩ (this slightly awkward rule ensures +that a `Stealth` arrow will have an opening angle of ⟨angle⟩ at its tip +if this option is used). As for the `length` key, if the optional +factors are given, they add a certain multiple of the line width to the +⟨dimension⟩ before the sine and cosines are computed. + + \tikz \draw [arrows = {-Stealth[inset=0pt, angle=90:10pt]}] (0,0) -- (1,0); + + \tikz \draw [arrows = {-Stealth[inset=0pt, angle=30:10pt]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/angle", + meta = "⟨angle⟩:⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/angle'"] = { + details = [[ +Sets the width of the arrow to twice the tangent of $⟨angle⟩/2$ times +the arrow length. This results in an arrow tip with an opening angle of +⟨angle⟩ at its tip and with the specified `length` unchanged. + + \tikz \draw [arrows = {-Stealth[inset=0pt, length=10pt, angle'=90]}] + (0,0) -- (1,0); + + \tikz \draw [arrows = {-Stealth[inset=0pt, length=10pt, angle'=30]}] + (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/angle'", + meta = "⟨angle⟩" + }, + ["arrow keys/arc"] = { + details = [[ +Sets the angle of arcs in arrows to ⟨degrees⟩. Note that this key is +quite different from the `angle` key, which is "just a fancy way of +setting the length and width". In contrast, the `arc` key is used to set +the degrees of arcs that are part of an arrow tip: + + \tikz [ultra thick] { + \draw [arrows = {-Hooks[]}] (0,1) -- (1,1); + \draw [arrows = {-Hooks[arc=90]}] (0,0.5) -- (1,0.5); + \draw [arrows = {-Hooks[arc=270]}] (0,0) -- (1,0); + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/arc", + meta = "⟨degrees⟩" + }, + ["arrow keys/bend"] = { + details = [[ +*Bending* an arrow tip is a radical solution to the problem of +positioning arrow tips on a curved line: The arrow tip is no longer +"rigid" but the drawing itself will now bend along the curve. This has +the advantage that all the problems of flexing with wrong tangents and +overflexing disappear. The downsides are longer computation times +(bending an arrow is *much* more expensive that flexing it, let alone +than quick mode) and also the fact that excessive bending can lead to +ugly arrow tips. On the other hand, for most arrow tips their bend +version are visually quite pleasing and create a sophisticated look: + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=20pt,bend]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); + \end{tikzpicture} + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{[bend,sep]>>>}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); + \end{tikzpicture} + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[bend,round,length=20pt]}] + (0,-.5) .. controls (1,-.5) and (0.25,0) .. (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/bend" + }, + ["arrow keys/cap angle"] = { + details = [[ +Sets `length` to an appropriate multiple of the line width so that the +angle of a `Triangle Cap` is exactly ⟨angle⟩ at the tip. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/cap:angle", + meta = "⟨angle⟩" + }, + ["arrow keys/color"] = { + details = [[ +Normally, an arrow tip gets the same color as the path to which it is +attached. More precisely, it will get the current "draw color", also +known as "stroke color", which you can set using `draw=`⟨some color⟩. By +adding the option `color=` to an arrow tip (note that an "empty" color +is specified in this way), you ask that the arrow tip gets this default +draw color of the path. Since this is the default behavior, you usually +do not need to specify anything: + + \tikz [ultra thick] \draw [red, arrows = {-Stealth}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [blue, arrows = {-Stealth}] (0,0) -- (1,0); + +Now, when you provide a ⟨color⟩ with this option, you request that the +arrow tip should get this color *instead* of the color of the main path: + + \tikz [ultra thick] \draw [red, arrows = {-Stealth[color=blue]}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [red, arrows = {-Stealth[color=black]}] (0,0) -- (1,0); + +Similar to the `color` option used in normal TikZ options, you may omit +the `color=` part of the option. Whenever an ⟨arrow key⟩ is encountered +that TikZ does not recognize, it will test whether the key is the name +of a color and, if so, execute `color=`⟨arrow key⟩. So, the first of the +above examples can be rewritten as follows: + + \tikz [ultra thick] \draw [red, arrows = {-Stealth[blue]}] (0,0) -- (1,0); + +The ⟨color⟩ will apply both to any drawing and filling operations used +to construct the path. For instance, even though the `Stealth` arrow +tips looks like a filled quadrilateral, it is actually constructed by +drawing a quadrilateral and then filling it in the same color as the +drawing (see the `fill` option below to see the difference). + +When `color` is set to an empty text, the drawing color is always used +to fill the arrow tips, even if a different color is specified for +filling the path: + + \tikz [ultra thick] \draw [draw=red, fill=red!50, arrows = {-Stealth[length=10pt]}] + (0,0) -- (1,1) -- (2,0); + +As you can see in the above example, the filled area is not quite what +you might have expected. The reason is that the path was actually +internally shortened a bit so that the end of the "fat line" as inside +the arrow tip and we get a "clear" arrow tip. + +In general, it is a good idea not to add arrow tips to paths that are +filled. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/color", + meta = "⟨color or empty⟩" + }, + ["arrow keys/fill"] = { + details = [[ +Use this key to explicitly set the color used for filling the arrow +tips. This color can be different from the color used to draw (stroke) +the arrow tip: + + \tikz { + \draw [help lines] (0,-.5) grid [step=1mm] (1,.5); + \draw [thick, red, arrows = {-Stealth[fill=white,length=15pt]}] (0,0) -- (1,0); + } + +You can also specify the special "color" `none`. In this case, the arrow +tip is not filled at all (not even with white): + + \tikz { + \draw [help lines] (0,-.5) grid [step=1mm] (1,.5); + \draw [thick, red, arrows = {-Stealth[fill=none,length=15pt]}] (0,0) -- (1,0); + } + +Note that such "open" arrow tips are a bit difficult to draw in some +case: The problem is that the line must be shortened by just the right +amount so that it ends exactly on the back end of the arrow tip. In some +cases, especially when double lines are used, this will not be possible. + +When you use both the `color` and `fill` option, the `color` option must +come first since it will reset the filling to the color specified for +drawing. + + \tikz { + \draw [help lines] (0,-.5) grid [step=1mm] (1,.5); + \draw [thick, red, arrows = {-Stealth[color=blue, fill=white, length=15pt]}] + (0,0) -- (1,0); + } + +Note that by setting `fill` to the special color `pgffillcolor`, you can +cause the arrow tips to be filled using the color used to fill the main +path. (This special color is always available and always set to the +current filling color of the graphic state.): + + \tikz [ultra thick] \draw [draw=red, fill=red!50, + arrows = {-Stealth[length=15pt, fill=pgffillcolor]}] + (0,0) -- (1,1) -- (2,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/fill", + meta = "⟨color or none⟩" + }, + ["arrow keys/flex"] = { + details = [[ +When the `bending` library is loaded, this key is applied to all arrow +tips by default. It has the following effect: + +1. Instead of simply shifting the visual end of the arrow along the + tangent of the curve's end, we really move it along the curve by the + necessary distance. This operation is more expensive than the + `quick` operation -- but not *that* expensive, only expensive enough + so that it is not selected by default for all arrow tips. Indeed, + some compromises are made in the implementation where accuracy was + traded for speed, so the distance by which the line end is shifted + is not necessarily *exactly* 6.25mm; only something reasonably + close. + +2. The supports of the line are updated accordingly so that the + shortened line will still follow *exactly* the original line. This + means that the curve deformation effect caused by the `quick` + command does not happen here. + +3. Next, the arrow tip is rotated and shifted as follows: First, we + shift it so that its tip is exactly at the tip end, where the + original line ended. Then, the arrow is rotated so the *the visual + end lies on the line*: + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); + \end{tikzpicture} + +As can be seen in the example, the `flex` option gives a result that is +visually pleasing and does not deform the path. + +There is, however, one possible problem with the `flex` option: The +arrow tip no longer points along the tangent of the end of the path. +This may or may not be a problem, put especially for larger arrow tips +readers will use the orientation of the arrow head to gauge the +direction of the tangent of the line. If this tangent is important (for +example, if it should be horizontal), then it may be necessary to +enforce that the arrow tip "really points in the direction of the +tangent". + +To achieve this, the `flex` option takes an optional ⟨factor⟩ parameter, +which defaults to `1`. This factor specifies how much the arrow tip +should be rotated: If set to `0`, the arrow points exactly along a +tangent to curve at its tip. If set to `1`, the arrow point exactly +along a line from the visual end point on the curve to the tip. For +values in the middle, we interpolate the rotation between these two +extremes; so `flex=.5` will rotate the arrow's visual end "halfway away +from the tangent towards the actual position on the line". + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex=0]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); + \end{tikzpicture} + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex=.5]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); + \end{tikzpicture} + +Note how in the above examples the red line is visible inside the open +arrow tip. Open arrow tips do not go well with a flex value other +than `1`. Here is a more realistic use of the `flex=0` key: + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,flex=0]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); + \end{tikzpicture} + +If there are several arrow tips on a path, the `flex` option positions +them independently, so that each of them lies optimally on the path: + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{[flex,sep]>>>}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/flex", + meta = "⟨factor⟩" + }, + ["arrow keys/flex'"] = { + details = [[ +The `flex’` key is almost identical to the `flex` key. The only +difference is that a factor of `1` corresponds to rotating the arrow tip +so that the instead of the visual end, the "ultimate back end" of the +arrow tip lies on the red path. In the example instead of having the +arrow tip at a distance of `6.25mm` from the tip lie on the path, we +have the point at a distance of `1cm` from the tip lie on the path: + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex']}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); + \end{tikzpicture} + +Otherwise, the factor works as for `flex` and, indeed `flex=0` and +`flex’=0` have the same effect. + +The main use of this option is not so much with an arrow tip like +`Stealth` but rather with tips like the standard `>` in the context of a +strongly curved line: + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Computer Modern Rightarrow[flex]}] + (0,-.5) .. controls (1,-.5) and (0.5,0) .. (1,0); + \end{tikzpicture} + +In the example, the `flex` option does not really flex the arrow since +for a tip like the Computer Modern arrow, the visual end is the same as +the arrow tip -- after all, the red line does, indeed, end almost +exactly where it used to end. + +Nevertheless, you may feel that the arrow tip looks "wrong" in the sense +that it should be rotated. This is exactly what the `flex’` option does +since it allows us to align the "back end" of the tip with the red line: + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Computer Modern Rightarrow[flex'=.75]}] + (0,-.5) .. controls (1,-.5) and (0.5,0) .. (1,0); + \end{tikzpicture} + +In the example, I used `flex’=.75` so as not to overpronounce the +effect. Usually, you will have to fiddle with it sometime to get the +"perfectly aligned arrow tip", but a value of `.75` is usually a good +start. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/flex'", + meta = "⟨factor⟩" + }, + ["arrow keys/harpoon"] = { + details = [[ +The key requests that only the "left half" of the arrow tip should +drawn: + + \tikz [ultra thick] \draw [arrows = {-Stealth[harpoon]}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [arrows = {->[harpoon]}] (0,0) -- (1,0); + +Unlike the `reversed` key, which all arrows tip kinds support at least +in a basic way, designers of arrow tips really need to take this key +into account in their arrow tip code and often a lot of special +attention needs to do be paid to this key in the implementation. For +this reason, only some arrow tips will support it. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/harpoon" + }, + ["arrow keys/inset"] = { + details = [[ +The key is relevant only for some arrow tips such as the `Stealth` arrow +tip. It specifies a distance by which something inside the arrow tip is +set inwards; for the `Stealth` arrow tip it is the distance by which the +back angle is moved inwards. + +The computation of the distance works in the same way as for `length` +and `width`: To the ⟨dimension⟩ we add ⟨line width factor⟩ times that +line width, where the line width is computed based on the ⟨outer factor⟩ +as described for the `length` key. + + \tikz \draw [arrows = {-Stealth[length=10pt, inset=5pt]}] (0,0) -- (1,0); + + \tikz \draw [arrows = {-Stealth[length=10pt, inset=2pt]}] (0,0) -- (1,0); + +For most arrows for which there is no "natural inset" like, say, +`Latex`, this key has no effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/inset", + meta = "⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/inset'"] = { + details = [[ +This key works like `inset`, only like `width’` the second parameter is +a factor of the arrow length rather than of the line width. For +instance, the `Stealth` arrow sets `inset’` to `0pt 0.325` to ensure +that the inset is always at $13/40$th of the arrow length if nothing +else is specified. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/inset'", + meta = "⟨dimension⟩ ⟨length factor⟩ ⟨line width factor⟩" + }, + ["arrow keys/left"] = { + details = [[ +A shorthand for `harpoon`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/left" + }, + ["arrow keys/length"] = { + details = [[ +\[length-arrow-key\] This parameter is usually the most important +parameter that governs the size of an arrow tip: The ⟨dimension⟩ that +you provide dictates the distance from the "very tip" of the arrow to +its "back end" along the line: + + \tikz{ + \draw [-{Stealth[length=5mm]}] (0,0) -- (2,0); + \draw [|<->|] (1.5,.4) -- node[above=1mm] {5mm} (2,.4); + } + + \tikz{ + \draw [-{Latex[length=5mm]}] (0,0) -- (2,0); + \draw [|<->|] (1.5,.4) -- node[above=1mm] {5mm} (2,.4); + } + + \tikz{ + \draw [-{Classical TikZ Rightarrow[length=5mm]}] (0,0) -- (2,0); + \draw [|<->|] (1.5,.6) -- node[above=1mm] {5mm} (2,.6); + } + +**The Line Width Factors.** Following the ⟨dimension⟩, you may put a +space followed by a ⟨line width factor⟩, which must be a plain number +(no `pt` or `cm` following). When you provide such a number, the size of +the arrow tip is not just ⟨dimension⟩, but rather +$⟨dimension⟩ + ⟨line width + factor⟩\cdot w$ where $w$ is the width of the to-be-drawn path. This +makes it easy to vary the size of an arrow tip in accordance with the +line width -- usually a very good idea since thicker lines will need +thicker arrow tips. + +As an example, when you write `length=0pt 5`, the length of the arrow +will be exactly five times the current line width. As another example, +the default length of a `Latex` arrow is `length=3pt 4.5 0.8`. Let us +ignore the 0.8 for a moment; the `3pt 4.5` then means that for the +standard line width of `0.4pt`, the length of a `Latex` arrow will be +exactly 4.8pt (3pt plus 4.5 times `0.4pt`). + +Following the line width factor, you can additionally provide an ⟨outer +factor⟩, again preceded by a space (the `0.8` in the above example). +This factor is taken into consideration only when the `double` option is +used, that is, when a so-called "inner line width". For a double line, +we can identify three different "line widths", namely the inner line +width $w_i$, the line width $w_o$ of the two outer lines, and the "total +line width" $w_t = w_i + 2w_o$. In the below examples, we have +$w_i = 3\mathrm{pt}$, $w_o=1\mathrm{pt}$, and $w_t = 5\mathrm{pt}$. It +is not immediately clear which of these line widths should be considered +as $w$ in the above formula $⟨dimension⟩ + ⟨line width factor⟩\cdot + w$ for the computation of the length. One can argue both for $w_t$ +and also for $w_o$. Because of this, you use the ⟨outer factor⟩ to +decide on one of them or even mix them: TikZ sets +$w = ⟨outer factor⟩ w_o + + (1-⟨outer factor⟩)w_t$. Thus, when the outer factor is $0$, as in +the first of the following examples and as is the default when it is not +specified, the computed $w$ will be the total line width $w_t = + 5\mathrm{pt}$. Since $w=5\mathrm{pt}$, we get a total length of +$15pt$ in the first example (because of the factor `3`). In contrast, in +the last example, the outer factor is 1 and, thus, +$w = w_o = \mathrm{1pt}$ and the resulting length is 3pt. Finally, for +the middle case, the "middle" between 5pt and 1pt is 3pt, so the length +is 9pt. + + \tikz \draw [line width=1pt, double distance=3pt, + arrows = {-Latex[length=0pt 3 0]}] (0,0) -- (1,0); + + \tikz \draw [line width=1pt, double distance=3pt, + arrows = {-Latex[length=0pt 3 .5]}] (0,0) -- (1,0); + + \tikz \draw [line width=1pt, double distance=3pt, + arrows = {-Latex[length=0pt 3 1]} ] (0,0) -- (1,0); + +**The Exact Length.** For an arrow tip kind that is just an outline that +is filled with a color, the specified length should *exactly* equal the +distance from the tip to the back end. However, when the arrow tip is +drawn by stroking a line, it is no longer obvious whether the `length` +should refer to the extend of the stroked lines' path or of the +resulting pixels (which will be wider because of the thickness of the +stroking pen). The rules are as follows: + +1. If the arrow tip consists of a closed path (like `Stealth` or + `Latex`), imagine the arrow tip drawn from left to right using a + miter line cap. Then the `length` should be the horizontal distance + from the first drawn "pixel" to the last drawn "pixel". Thus, the + thickness of the stroked line and also the miter ends should be + taken into account: + + \tikz{ + \draw [line width=1mm, -{Stealth[length=10mm, open]}] + (0,0) -- (2,0); + \draw [|<->|] (2,.6) -- node[above=1mm] {10mm} ++(-10mm,0); + } + +2. If, in the above case, the arrow is drawn using a round line join + (see Section ?? for details on how to select this), the size of the + arrow should still be the same as in the first case (that is, as if + a miter join were used). This creates some "visual consistency" if + the two modes are mixed or if you later want to change the mode. + + \tikz{ + \draw [line width=1mm, -{Stealth[length=10mm, open, round]}] + (0,0) -- (2,0); + \draw [|<->|] (2,.6) -- node[above=1mm] {10mm} ++(-10mm,0); + } + + As the above example shows, however, a rounded arrow will still + exactly "tip" the point where the line should end (the point `(2,0)` + in the above case). It is only the scaling of the arrow that is not + affected. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/length", + meta = "⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/line cap"] = { + details = [[ +Sets the line cap of all lines that are drawn in the arrow to a round +cap or a butt cap. (Unlike for normal lines, the `rect` cap is not +allowed.) Naturally, this key has no effect for arrows whose paths are +closed. + +Each arrow tip has a default value for the line cap, which can be +overruled using this option. + +Changing the cap should have no effect on the size of the arrow. +However, it will have an effect on where the exact "tip" of the arrow is +since this will always be exactly at the end of the arrow: + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line cap=butt]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line cap=round]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line cap=butt]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line cap=round]}] + (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/line:cap", + meta = "⟨round or butt⟩" + }, + ["arrow keys/line join"] = { + details = [[ +Sets the line join to round or miter (`bevel` is not allowed). This +time, the key only has an effect on paths that have "corners" in them. +The same rules as for `line cap` apply: the size is not affects, but the +tip end is: + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line join=miter]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line join=round]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line join=miter]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line join=round]}] + (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/line:join", + meta = "⟨round or miter⟩" + }, + ["arrow keys/line width"] = { + details = [[ +This key sets the line width inside an arrow tip for drawing (out)lines +of the arrow tip. When you set this width to `0pt`, which makes sense +only for closed tips, the arrow tip is only filled. This can result in +better rendering of some small arrow tips and in case of bend arrow tips +(because the line joins will also be bend and not "mitered".) + +The meaning of the factors is as usual the same as for `length` or +`width`. + + \tikz \draw [arrows = {-Latex[line width=0.1pt, fill=white, length=10pt]}] (0,0) -- (1,0); + + \tikz \draw [arrows = {-Latex[line width=1pt, fill=white, length=10pt]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/line:width", + meta = "⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/line width'"] = { + details = [[ +Works like `line width` only the factor is with respect to the `length`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/line:width'", + meta = "⟨dimension⟩ ⟨length factor⟩" + }, + ["arrow keys/n"] = { + details = [[ +Sets the number of rays in a `Rays` arrow tip. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/n", + meta = "⟨number⟩" + }, + ["arrow keys/open"] = { + details = [[ +A shorthand for `fill=none`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/open" + }, + ["arrow keys/quick"] = { + details = [[ +Recall that curves in TikZ are actually Bézier curves, which means that +they start and end at certain points and we specify two vectors, one for +the start and one for the end, that provide tangents to the curve at +these points. In particular, for the end of the curve, there is a point +called the *second support point* of the curve such that a tangent to +the curve at the end goes through this point. In our above example, the +second support point is at the middle of the light red line and, indeed, +a tangent to the red line at the point touching the wall is perfectly +horizontal. + +In order to add our arrow tip to the curved path, our first objective is +to "shorten" the path by 6.25mm. Unfortunately, this is now much more +difficult than for a straight path. When the `quick` option is added to +an arrow tip (it is also the default if no special libraries are +loaded), we cheat somewhat: Instead of really moving along 6.25mm along +the path, we simply shift the end of the curve by 6.25mm *along the +tangent* (which is easy to compute). We also have to shift the second +support point by the same amount to ensure that the line still has the +same tangent at the end. This will result in the following: + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,quick]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); + \end{tikzpicture} + +They main problem with the above picture is that the red line is no +longer equal to the original red line (notice much sharper curvature +near its end). In our example this is not such a bad thing, but it +certainly "not a nice thing" that adding arrow tips to a curve changes +the overall shape of the curves. This is especially bothersome if there +are several similar curves that have different arrow heads. In this +case, the similar curves now suddenly look different. + +Another big problem with the above approach is that it works only well +if there is only a single arrow tip. When there are multiple ones, +simply shifting them along the tangent as the `quick` option does +produces less-than-satisfactory results: + + \begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{[quick,sep]>>>}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); + \end{tikzpicture} + +Note that the third arrow tip does not really lie on the curve any more. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/quick" + }, + ["arrow keys/reversed"] = { + details = [[ +Adding this key to an arrow tip will "reverse its direction" so that is +points in the opposite direction (but is still at that end of the line +where the non-reversed arrow tip would have been drawn; so only the tip +is reversed). For most arrow tips, this just results in an internal flip +of a coordinate system, but some arrow tips actually use a slightly +different version of the tip for reversed arrow tips (namely when the +joining of the tip with the line would look strange). All of this +happens automatically, so you do not need to worry about this. + +If you apply this key twice, the effect cancels, which is useful for the +definition of shorthands (which will be discussed later). + + \tikz [ultra thick] \draw [arrows = {-Stealth[reversed]}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [arrows = {-Stealth[reversed, reversed]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/reversed" + }, + ["arrow keys/right"] = { + details = [[ +A shorthand for `harpoon, swap`. + + \tikz [ultra thick] \draw [arrows = {-Stealth[left]}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [arrows = {-Stealth[right]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/right" + }, + ["arrow keys/round"] = { + details = [[ +A shorthand for `line cap=round, line join=round`, resulting in +"rounded" arrow heads. + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[round]}] (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,round]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/round" + }, + ["arrow keys/sep"] = { + details = [[ +When a sequence of arrow tips is specified in an arrow tip specification +for the end of the line, the arrow tips are normally arranged in such a +way that the tip of each arrow ends exactly at the "back end" of the +next arrow tip (for start specifications, the ordering is inverted, of +course). Now, when the `sep` option is set, instead of exactly touching +the back end of the next arrow, the specified ⟨dimension⟩ is added as +additional space (the distance may also be negative, resulting in an +overlap of the arrow tips). The optional factors have the same meaning +as for the `length` key, see that key for details. + +Let us now have a look at some examples. First, we use two arrow tips +with different separations between them: + + \tikz { + \draw [-{>[sep=1pt]>[sep= 2pt]>}] (0,1.0) -- (1,1.0); + \draw [-{>[sep=1pt]>[sep=-2pt]>}] (0,0.5) -- (1,0.5); + \draw [-{> >[sep] >}] (0,0.0) -- (1,0.0); + } + +You can also specify a `sep` for the last arrow tip in the sequence (for +end specifications, otherwise for the first arrow tip). In this case, +this first arrow tip will not exactly "touch" the point where the path +ends, but will rather leave the specified amount of space. This is +usually quite desirable. + + \tikz { + \node [draw] (A) {A}; + \node [draw] (B) [right=of A] {B}; + + \draw [-{>>[sep=2pt]}] (A) to [bend left=45] (B); + \draw [- >> ] (A) to [bend right=45] (B); + } + +Indeed, adding a `sep` to an arrow tip is *very* desirable, so you will +usually write something like `>={To[sep]}` somewhere near the start of +your files. + +One arrow tip kind can be quite useful in this context: The arrow tip +kind `_ `. It draws nothing and has zero length, *but* it has `sep` set +as a default option. Since it is a single letter shorthand, you can +write short and clean "code" in this way: + + \tikz \draw [->_>] (0,0) -- (1,0); + + \tikz \draw [->__>] (0,0) -- (1,0); + +However, using the `sep` option will be faster than using the `_ ` arrow +tip and it also allows you to specify the desired length directly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/sep", + meta = "⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/sharp"] = { + details = [[ +A shorthand for `line cap=butt, line join=miter`, resulting in "sharp" +or "pointed" arrow heads. + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[sharp]}] (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,sharp]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/sharp" + }, + ["arrow keys/slant"] = { + details = [[ +Slanting is used to create an "italics" effect for arrow tips: All arrow +tips get "slanted" a little bit relative to the axis of the arrow: + + \tikz { + \draw [arrows = {->[]}] (0,1) -- (1,1); + \draw [arrows = {->[slant=.5]}] (0,0.5) -- (1,0.5); + \draw [arrows = {->[slant=1]}] (0,0) -- (1,0); + } + +There is one thing to note about slanting: Slanting is done using a +so-called "canvas transformation" and has no effect on positioning of +the arrow tip. In particular, if an arrow tip gets slanted so strongly +that it starts to protrude over the arrow tip end, this does not change +the positioning of the arrow tip. + +Here is another example where slanting is used to match italic text: + + \tikz [>={[slant=.3] To[] To[]}] + \graph [math nodes] { A -> B <-> C }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/slant", + meta = "⟨factor⟩" + }, + ["arrow keys/swap"] = { + details = [[ +This key flips that arrow tip along the axis of the line. It makes sense +only for asymmetric arrow tips like the harpoons created using the +`harpoon` option. + + \tikz [ultra thick] \draw [arrows = {-Stealth[harpoon]}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [arrows = {-Stealth[harpoon,swap]}] (0,0) -- (1,0); + +Swapping is always possible, no special code is needed on behalf of an +arrow tip implementer. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/swap" + }, + ["arrow keys/width"] = { + details = [[ +This key works like the `length` key, only it specifies the "width" of +the arrow tip; so if width and length are identical, the arrow will just +touch the borders of a square. (An exception to this rule are "halved" +arrow tips, see Section ??.) The meaning of the two optional factor +numbers following the ⟨dimension⟩ is the same as for the `length` key. + + \tikz \draw [arrows = {-Latex[width=10pt, length=10pt]}] (0,0) -- (1,0); + + \tikz \draw [arrows = {-Latex[width=0pt 10, length=10pt]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/width", + meta = "⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/width'"] = { + details = [[ +The key (note the prime) has a similar effect as the `width` key. The +difference is that the second, still optional parameter ⟨length factor⟩ +specifies the width of the key not as a multiple of the line width, but +as a multiple of the arrow length. + +The idea is that if you write, say, `width’=0pt 0.5`, the width of the +arrow will be half its length. Indeed, for standard arrow tips like +`Stealth` the default width is specified in this way so that if you +change the length of an arrow tip, you also change the width in such a +way that the aspect ratio of the arrow tip is kept. The other way round, +if you modify the factor in `width’` without changing the length, you +change the aspect ratio of the arrow tip. + +Note that later changes of the length are taken into account for the +computation. For instance, if you write + + length = 10pt, width'=5pt 2, length=7pt + +the resulting width will be $19\mathrm{pt} = 5\mathrm{pt} + 2\cdot + 7\mathrm{pt}$. + + \tikz \draw [arrows = {-Latex[width'=0pt .5, length=10pt]}] (0,0) -- (1,0); + + \tikz \draw [arrows = {-Latex[width'=0pt .5, length=15pt]}] (0,0) -- (1,0); + +The third, also optional, parameter allows you to add a multiple of the +line width to the value computed in terms of the length. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/width'", + meta = "⟨dimension⟩ ⟨length factor⟩ ⟨line width factor⟩" + }, + ["arrows keys/scale"] = { + details = [[ +After all the other options listed in the previous (and also the +following sections) have been processed, TikZ applies a *scaling* to the +computed length, inset, and width of the arrow tip (and, possibly, to +other size parameters defined by special-purpose arrow tip kinds). +Everything is simply scaled by the given ⟨factor⟩. + + \tikz { + \draw [arrows = {-Stealth[]}] (0,1) -- (1,1); + \draw [arrows = {-Stealth[scale=1.5]}] (0,0.5) -- (1,0.5); + \draw [arrows = {-Stealth[scale=2]}] (0,0) -- (1,0); + } + +Note that scaling has *no* effect on the line width (as usual) and also +not on the arrow padding (the `sep`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrows:keys/scale", + meta = "⟨factor⟩" + }, + ["arrows keys/scale length"] = { + details = [[ +This factor works like `scale`, only it is applied only to dimensions +"along the axis of the arrow", that is, to the length and to the inset, +but not to the width. + + \tikz { + \draw [arrows = {-Stealth[]}] (0,1) -- (1,1); + \draw [arrows = {-Stealth[scale length=1.5]}] (0,0.5) -- (1,0.5); + \draw [arrows = {-Stealth[scale length=2]}] (0,0) -- (1,0); + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrows:keys/scale:length", + meta = "⟨factor⟩" + }, + ["arrows keys/scale width"] = { + details = [[ +Like `scale length`, but for dimensions related to the width. + + \tikz { + \draw [arrows = {-Stealth[]}] (0,1) -- (1,1); + \draw [arrows = {-Stealth[scale width=1.5]}] (0,0.5) -- (1,0.5); + \draw [arrows = {-Stealth[scale width=2]}] (0,0) -- (1,0); + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrows:keys/scale:width", + meta = "⟨factor⟩" + }, + aspect = { + details = [[ +The aspect is a recommendation for the quotient of the radii of the +cylinder end. This may be ignored if the shape is enlarged to some +minimum width. + + \begin{tikzpicture}[] + \tikzset{every node/.style={cylinder, shape border rotate=90, draw}} + \node [aspect=1.0] {A}; + \node [aspect=0.5] at (1,0) {B}; + \node [aspect=0.25] at (2,0) {C}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/aspect", + meta = "⟨value⟩" + }, + ["bar interval shift"] = { + details = [[ +\[key-bar-interval-shift\] + +Sets the *relative* shift of `\pgfplothandlerxbarinterval` and +`\pgfplothandlerybarinterval` to ⟨factor⟩. As `/pgf/bar interval width`, +the argument is relative to the interval length of the input +coordinates. + +The argument `{scale}` will be evaluated using the math parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/bar:interval:shift", + meta = "{factor}" + }, + ["bar interval width"] = { + details = [[ +\[key-bar-interval-width\] + +Sets the *relative* width of `\pgfplothandlerxbarinterval` and +`\pgfplothandlerybarinterval` to `{scale}`. The argument is relative to +$(x_{i+1} - x_i)$ for $y$ bar plots and relative to $(y_{i+1}-y_i)$ for +$x$ bar plots. + +The argument `{scale}` will be evaluated using the math parser. + + \begin{tikzpicture}[bar interval width=0.5] + \draw[gray] + (0,3) -- (0,-0.1) + (1,3) -- (1,-0.1) + (2,3) -- (2,-0.1) + (4,3) -- (4,-0.1); + \pgfplothandlerybarinterval + \begin{scope}[bar interval shift=0.25,fill=blue] + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{2cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}} + \pgfplotstreamend + \pgfusepath{fill} + \end{scope} + \begin{scope}[bar interval shift=0.75,fill=red] + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{3cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{0.2cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.7cm}} + \pgfplotstreampoint{\pgfpoint{4cm}{0.2cm}} + \pgfplotstreamend + \pgfusepath{fill} + \end{scope} + \end{tikzpicture} + +Please note that bars are always centered, so we have to use shifts +$0.25$ and $0.75$ instead of $0$ and $0.5$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/bar:interval:width", + meta = "{scale}" + }, + ["bar shift"] = { + details = [[ +Sets a shift used by `\pgfplothandlerxbar` and `\pgfplothandlerybar` to +`{dimension}`. It has the same effect as `xshift`, but it applies only +to those bar plots. The argument `{dimension}` will be evaluated using +the math parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/bar:shift", + meta = "{dimension}" + }, + ["bar width"] = { + details = [[ +Sets the width of `\pgfplothandlerxbar` and `\pgfplothandlerybar` to +`{dimension}`. The argument `{dimension}` will be evaluated using the +math parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/bar:width", + meta = "{dimension}" + }, + ["buffer gate IEC symbol"] = { + details = [[ +Set the symbol for the `buffer gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `buffer gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/buffer:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["callout absolute pointer"] = { + details = [[ +Sets the vector of the callout pointer absolutely within the picture. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:absolute:pointer", + meta = "⟨coordinate⟩" + }, + ["callout pointer arc"] = { + details = [[ +Sets the width of the pointer at the border of the ellipse according to +an arc of length ⟨angle⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:arc", + meta = "⟨angle⟩" + }, + ["callout pointer end size"] = { + details = [[ +Sets the size of the last ellipse in the pointer. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:end:size", + meta = "⟨value⟩" + }, + ["callout pointer segments"] = { + details = [[ +Sets the number of segments in the pointer. Note that PGF will happily +overlap segments if too many are specified. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:segments", + meta = "⟨number⟩" + }, + ["callout pointer shorten"] = { + details = [[ +Moves the callout pointer towards the center of the callout's main shape +by ⟨distance⟩. + + \begin{tikzpicture} + \tikzset{callout/.style={ellipse callout, callout pointer arc=30, + callout absolute pointer={#1}}} + \draw (0,0) grid (3,2); + \node[callout={(3,1.5)}, fill=red!50] at (0,1.5) {A}; + \node[callout={(3,.5)}, fill=green!50, callout pointer shorten=1cm] + at (0,.5) {B}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:shorten", + meta = "⟨distance⟩" + }, + ["callout pointer start size"] = { + details = [[ +Sets the size of the first segment in the pointer (i.e., the segment +nearest the main cloud shape). There are three possible forms for +⟨value⟩: + +- A single dimension (e.g., `5pt`), in which case the first ellipse + will have equal diameters of 5pt. + +- Two dimensions (e.g., `10pt and 2.5pt`), which sets the $x$ and $y$ + diameters of the first ellipse. + +- A decimal fraction (e.g., `.2 of callout`), in which case the $x$ + and $y$ diameters of the first ellipse will be set as fractions of + the width and height of the main shape. The keyword `of callout` + cannot be omitted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:start:size", + meta = "⟨value⟩" + }, + ["callout pointer width"] = { + details = [[ +Sets the width of the pointer at the border of the rectangle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:width", + meta = "⟨length⟩" + }, + ["callout relative pointer"] = { + details = [[ +Sets the vector of the callout pointer 'relative' to the callout shape. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:relative:pointer", + meta = "⟨coordinate⟩" + }, + ["chamfered rectangle angle"] = { + details = [[ +Sets the angle *from the vertical* for the chamfer. + + \begin{tikzpicture} + \tikzset{every node/.style={chamfered rectangle, draw}} + \node[chamfered rectangle angle=30] {abc}; + \node[chamfered rectangle angle=60] at (1.5,0) {123}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/chamfered:rectangle:angle", + meta = "⟨angle⟩" + }, + ["chamfered rectangle corners"] = { + details = [[ +Specifies which corners are chamfered. The corners are identified by +their "compass point" directions (i.e. `north east`, `north west`, +`south west`, and `south east`), and must be separated by commas (so if +there is more than one corner in the list, it must be surrounded by +braces). Any corners not mentioned in ⟨list⟩ are automatically not +chamfered. Two additional values `chamfer all` and `chamfer none`, are +also permitted. + + \begin{tikzpicture} + \tikzset{every node/.style={chamfered rectangle, draw}} + \node[chamfered rectangle corners=north west] {ghi}; + \node[chamfered rectangle corners={north east, south east}] at (1.5,0) {789}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/chamfered:rectangle:corners", + meta = "⟨list⟩" + }, + ["chamfered rectangle sep"] = { + details = [[ +Sets both the `xsep` and `ysep` simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/chamfered:rectangle:sep", + meta = "⟨length⟩" + }, + ["chamfered rectangle xsep"] = { + details = [[ +Sets the distance that the chamfer extends horizontally beyond the node +contents (which includes the `inner sep`). If ⟨length⟩ is large, such +that the top and bottom chamfered edges would cross, then ⟨length⟩ is +ignored and the chamfered edges are drawn so that they meet in the +middle. + + \begin{tikzpicture} + \tikzset{every node/.style={chamfered rectangle, draw}} + \node[chamfered rectangle xsep=2pt] {def}; + \node[chamfered rectangle xsep=2cm] at (1.5,0) {456}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/chamfered:rectangle:xsep", + meta = "⟨length⟩" + }, + ["chamfered rectangle ysep"] = { + details = [[ +Sets the distance that the chamfer extends vertically beyond the node +contents. If ⟨length⟩ is large, such that the left and right chamfered +edges would cross, then ⟨length⟩ is ignored and the chamfered edges are +drawn so that they meet in the middle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/chamfered:rectangle:ysep", + meta = "⟨length⟩" + }, + ["circular sector angle"] = { + details = [[ +Sets the central angle of the sector. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/circular:sector:angle", + meta = "⟨angle⟩" + }, + ["cloud ignores aspect"] = { + details = [[ +Instruct PGF to ignore the `aspect` key. Internally, the TeX-if +`\ifpgfcloudignoresaspect` is set appropriately. The initial value is +`false`. + + \begin{tikzpicture}[aspect=1, every node/.style={cloud, cloud puffs=11, draw}] + \node [fill=gray!20] {rain}; + \node [cloud ignores aspect, fill=white] at (1.5,0) {snow}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cloud:ignores:aspect", + meta = "⟨boolean⟩" + }, + ["cloud puff arc"] = { + details = [[ +Sets the length of the puff arc (in degrees). A shorter arc can produce +better looking joins between puffs for larger line widths. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cloud:puff:arc", + meta = "⟨angle⟩" + }, + ["cloud puffs"] = { + details = [[ +Sets the number of puffs for the cloud. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cloud:puffs", + meta = "⟨integer⟩" + }, + ["cylinder body fill"] = { + details = [[ +Sets the color for the body of the cylinder. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cylinder:body:fill", + meta = "⟨color⟩" + }, + ["cylinder end fill"] = { + details = [[ +Sets the color for the end of the cylinder. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cylinder:end:fill", + meta = "⟨color⟩" + }, + ["cylinder uses custom fill"] = { + details = [[ +This enables the use of a custom fill for the body and the end of the +cylinder. The background path for the shape should not be filled (e.g., +in TikZ, the `fill` option for the node must be implicity or explicitly +set to `none`). Internally, this key sets the TeX-if +`\ifpgfcylinderusescustomfill` appropriately. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cylinder:uses:custom:fill", + meta = "⟨boolean⟩" + }, + ["dart tail angle"] = { + details = [[ +Sets the angle between the tails of the dart. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/dart:tail:angle", + meta = "⟨angle⟩" + }, + ["dart tip angle"] = { + details = [[ +Sets the angle at the tip of the dart. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/dart:tip:angle", + meta = "⟨angle⟩" + }, + ["data visualization/style sheets/⟨style sheet⟩/default style"] = { + details = [[ +This key gets during styling whenever +`/pgf/data visualization/style sheet/`⟨style sheet⟩`/`⟨value⟩ is not +defined. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data:visualization/style:sheets/⟨style:sheet⟩/default:style", + meta = "⟨value⟩" + }, + ["data/format"] = { + details = [[ +Use this key to locally set the format used for parsing the data. The +⟨format⟩ must be a format that has been previously declared using the +`\pgfdeclaredataformat` command. See the reference section for a list of +the predefined formats. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/format", + meta = "⟨format⟩" + }, + ["data/headline"] = { + details = [[ +When this key is set to a non-empty value, the value of ⟨headline⟩ is +used as the headline and the first line of the data is treated as a +normal line rather than as a headline. + + \begin{tikzpicture} + \datavisualization [school book axes, visualize as line] + data [headline={x, y}] { + 0, 0 + 1, 1 + 2, 1 + 3, 0 + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/headline", + meta = "⟨headline⟩" + }, + ["data/inline"] = { + details = [[ +This is a shorthand file `read from file={}`. You can add this to make +it clear(er) to the reader that data follows inline. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/inline" + }, + ["data/new set"] = { + details = [[ +Creates an empty data set called ⟨name⟩. If a data set of the same name +already exists, it is overwritten and made empty. Data sets are global. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/new:set", + meta = "⟨name⟩" + }, + ["data/read from file"] = { + details = [[ +If you set the `read from file` attribute to a non-empty ⟨filename⟩, the +data will be read from this file. In this case, no ⟨inline data⟩ may be +present, not even empty curly braces should be provided. If +`read from file` is empty, the data must directly follow as ⟨inline +data⟩. + + % Data is read from two external files: + \pgfdata[format=table, read from file=file1.csv] + \pgfdata[format=table, read from file=file2.csv] + + % Data is given inline: + \pgfdata[format=table] + { + x, y + 1, 2 + 2, 3 + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/read:from:file", + meta = "⟨filename⟩" + }, + ["data/samples"] = { + details = [[ +Sets the number of samples to be used when no sample number is +specified. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/samples", + meta = "⟨number⟩" + }, + ["data/separator"] = { + details = [[ +Use this key to change which character is used to separate values in the +headline and in the data lines. To set the separator to a space, either +set this key to an empty value or say `separator=\space`. Note that you +must surround a comma by curly braces if you which to (re)set the +separator character to a space. + + \begin{tikzpicture} + \datavisualization [school book axes, visualize as line] + data [separator=\space] { + x y + 0 0 + 1 1 + 2 1 + 3 0 + } + data [separator=;] { + x; y; z + 3; 1; 0 + 2; 2; 0 + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/separator", + meta = "⟨character⟩" + }, + ["data/set"] = { + details = [[ +Shorthand for `/data point/set=`⟨name⟩. + + \tikz \datavisualization + [scientific axes=clean, + visualize as line=sin, + visualize as line=cos] + data [set=sin] { + x, y + 0, 0 + 1, 1 + 2, 0 + 3, -1 + 4, 0 + } + data [set=cos] { + x, y + 0, 1 + 1, 0 + 2, -1 + 3, 0 + 4, 1 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/set", + meta = "⟨name⟩" + }, + ["data/store in set"] = { + details = [[ +When this key is set to any non-empty ⟨name⟩ and if this ⟨name⟩ has +previously been used with the `new set` key, then the following happens: +For the current `\pgfdata` command, all parsed data is not passed to the +rendering pipeline. Instead, the parsed data is appended to the data set +⟨name⟩. This includes all options parsed to the `\pgfdata` command, +which is why neither this key nor the previous key should be passed as +options to a `\pgfdata` command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/store:in:set", + meta = "⟨name⟩" + }, + ["data/use set"] = { + details = [[ +This works similar to `read from file`. When this key is used with a +`\pgfdata` command, no inline data may follow. Instead, the data stored +in the data set ⟨name⟩ is used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/use:set", + meta = "⟨name⟩" + }, + ["declare function"] = { + details = [[ +This key allows simple functions to be created locally. Its use is +perhaps best illustrated by an example: + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + \draw [blue, thick, x=0.0085cm, y=1cm, + declare function={ + sines(\t,\a,\b)=1 + 0.5*(sin(\t)+sin(\t*\a)+sin(\t*\b)); + }] + plot [domain=0:360, samples=144, smooth] (\x,{sines(\x,3,5)}); + \end{tikzpicture} + +Each definition in ⟨function definitions⟩ takes the form +⟨name⟩`(`⟨arguments⟩`)=`⟨definition⟩`;` (note the semicolon at the end, +this is very important). If multiple functions are being defined, the +semicolon is used to separate them (*not* a comma). The function ⟨name⟩ +can be any name that is not already a function name in the current +scope. The list of ⟨arguments⟩ are commands such as `\x`, or `\y` (it is +not possible to declare functions that take variable numbers of +arguments using this key). If the function takes no arguments, then the +parentheses need not be used. The ⟨definition⟩ should be an expression +that can be parsed by the mathematical engine and should use the +commands specified in ⟨arguments⟩. + +When specifying multiple functions, functions that appear later on in +⟨function definitions⟩ can refer to earlier functions: + + \begin{tikzpicture}[ + declare function={ + excitation(\t,\w) = sin(\t*\w); + noise = rnd - 0.5; + source(\t) = excitation(\t,20) + noise; + filter(\t) = 1 - abs(sin(mod(\t, 90))); + speech(\t) = 1 + source(\t)*filter(\t); + } + ] + \draw [help lines] (0,0) grid (3,2); + \draw [blue, thick, x=0.0085cm, y=1cm] (0,1) -- + plot [domain=0:360, samples=144, smooth] (\x,{speech(\x)}); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/declare:function", + meta = "⟨function definitions⟩" + }, + ["declare function/execute at begin function"] = { + details = [[ +These ⟨tokens⟩ are inserted just before `\pgfmathdeclarefunction` scans +the body of the function definition. This is a rather low-level option, +so you should read the implementation to figure out where the ⟨tokens⟩ +are inserted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/declare:function/execute:at:begin:function", + meta = "⟨tokens⟩" + }, + ["declare function/execute at end function"] = { + details = [[ +These ⟨tokens⟩ are inserted just after `\pgfmathdeclarefunction` has +finished scanning the body of the function definition. This is a rather +low-level option, so you should read the implementation to figure out +where the ⟨tokens⟩ are inserted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/declare:function/execute:at:end:function", + meta = "⟨tokens⟩" + }, + ["declare function/ignore spaces"] = { + details = [[ +Uses the two previously described keys +`/pgf/declare function/execute at begin function` and +`/pgf/declare function/execute at end function` to install catcodes such +that spaces inside the body of the function definition of +`\pgfmathdeclarefunction` are ignored. The usual TeX tokenization rules +apply, so if the body of the function had already been tokenized by +other means this will become ineffective. If you want to use a space you +can use ` ` in the function body which has its catcode set to 10 +(space). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/declare:function/ignore:spaces", + meta = "⟨boolean⟩" + }, + decoration = { + details = [[ +This option is used to specify which decoration is used and how it will +look like. Note that this key will *not* cause any decorations to be +applied, immediately. It takes the `decorate` path command or the +`decorate` option to actually decorate a path. The `decoration` option +is only used to specify which decoration should be used, in principle. +You can also use this option at the beginning of a picture or a scope to +specify the decoration to be used with each invocation of the `decorate` +path command. Naturally, any local options of the `decorate` path +command override these "global" options. + + \begin{tikzpicture}[decoration=zigzag] + \draw decorate {(0,0) -- (3,2)}; + \draw [red] decorate [decoration=crosses] {(0,2) -- (3,0)}; + \end{tikzpicture} + +The ⟨decoration options⟩ are special options (which have the path prefix +`/pgf/decoration/`) that determine the properties of the decoration. +Which options are appropriate for a decoration strongly depend on the +decoration, you will have to look up the appropriate options in the +documentation of the decoration, see Section ??. + +There is one option (available only in TikZ) that is special: + +Further options allow you to adjust the position of decorations relative +to the to-be-decorated path. See Section ?? below for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration", + meta = "⟨decoration options⟩" + }, + ["decoration automaton/auto corner on length"] = { + details = [[ +This key has the following effect: Firstly, in case the TeX-if +`\ifpgfdecoratepathhascorners` is false, nothing happens. Otherwise, it +is tested whether the remaining distance on the current input segment is +at most ⟨dimension⟩. If so, a `lineto` operation is used to reach the +end of this input segment and the automaton continues with the next +input segment, but remains in the current state. + +The main idea behind this option is to avoid having decoration segments +"overshoot" past a corner. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/auto:corner:on:length", + meta = "⟨dimension⟩" + }, + ["decoration automaton/auto end on length"] = { + details = [[ +This key is just included for convenience, it does nothing that cannot +be achieved using the previous options. The effect is the following: If +the remaining input path's length is at most ⟨dimension⟩, the decorated +path is ended with a straight line to the end of the input path and, +possibly, it is closed, namely if the input path ended with a closepath +operation. Otherwise, it is checked whether the current input segment is +a closepath segment and whether the remaining distance on the current +input segment is at most ⟨distance⟩. If so, then a closepath operation +is used to close the decorated path and the automaton continues with the +next subpath, remaining in the current state. + +In all other cases, nothing happens. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/auto:end:on:length", + meta = "⟨dimension⟩" + }, + ["decoration automaton/if input segment is closepath"] = { + details = [[ +This key checks whether the current input segment is a closepath +operation. If so, the ⟨options⟩ get executed; otherwise nothing happens. +You can use this option to handle a closepath in some special way, for +instance, switching to a new state in which `\pgfpathclose` is executed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/if:input:segment:is:closepath", + meta = "⟨options⟩" + }, + ["decoration automaton/next state"] = { + details = [[ +After the ⟨code⟩ for state has been executed for the last time, a state +switch to ⟨new state⟩ is performed. If this option is not given, the +next state is the same as the current state. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/next:state", + meta = "⟨new state⟩" + }, + ["decoration automaton/persistent postcomputation"] = { + details = [[ +Works like the `persistent precomputation` option, only the ⟨postcode⟩ +is executed after (and also outside) the TeX-group of the main ⟨code⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/persistent:postcomputation", + meta = "⟨postcode⟩" + }, + ["decoration automaton/persistent precomputation"] = { + details = [[ +If the ⟨code⟩ of the state is executed, the ⟨precode⟩ is executed first +and it is executed outside the TeX-group of the ⟨code⟩. Note that when +the ⟨precode⟩ is executed, the transformation matrix is not set up. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/persistent:precomputation", + meta = "⟨precode⟩" + }, + ["decoration automaton/repeat state"] = { + details = [[ +Tells PGF how long the automaton stays "normally" in the current state. +This count is reset to ⟨repetitions⟩ each time one of the `switch if` +keys causes a state switch. If no state switches occur, the ⟨code⟩ is +executed and the repetition counter is decreased. Then, there is once +more a chance of a state change caused by any of the ⟨options⟩. If no +repetition occurs, the ⟨code⟩ is executed once more and the counter is +decreased once more. When the counter reaches zero, the ⟨code⟩ is +executed once more, but, then, a different state is entered, as +specified by the `next state` option. + +Note, that the maximum number of times the state will be executed is +$⟨repetitions⟩+1$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/repeat:state", + meta = "⟨repetitions⟩" + }, + ["decoration automaton/switch if input segment less than"] = { + details = [[ +When this key is encountered, PGF checks whether the remaining distance +to the end of the current input segment of the input path is less than +⟨dimension⟩. If so, an immediate state switch to ⟨new state⟩ occurs. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/switch:if:input:segment:less:than", + meta = " ⟨dimension⟩ to ⟨new state⟩" + }, + ["decoration automaton/switch if less than"] = { + details = [[ +When this key is encountered, PGF checks whether the remaining distance +to the end of the input path is less than ⟨dimension⟩. If so, an +immediate state switch to ⟨new state⟩ occurs. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/switch:if:less:than", + meta = "⟨dimension⟩ to ⟨new state⟩" + }, + ["decoration automaton/width"] = { + details = [[ +First, this option causes an immediate switch to the state `final` if +the remaining distance on the input path is less than ⟨dimension⟩. The +effect is the same as if you had said +`switch if less than=`⟨dimension⟩` to final` just before the `width` +option. + +If no switch occurs, this option tells PGF the width of the segment. The +current point will travel along the input path (as described earlier) by +this distance. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/width", + meta = "⟨dimension⟩" + }, + ["decoration/amplitude"] = { + details = [[ +This key determines the "desired height" (or amplitude) of decorations +for which this makes sense. For instance, the initial value of `2.5pt` +means that deforming decorations should deform a path by up to 2.5pt +away from the original path. + +This key sets the TeX-dimension `\pgfdecorationsegmentamplitude`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/amplitude", + meta = "⟨dimension⟩" + }, + ["decoration/anchor"] = { + details = [[ +The anchor used to position the shape backgrounds. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/anchor", + meta = "⟨anchor⟩" + }, + ["decoration/angle"] = { + details = [[ +The way some decorations look like depends on a configurable angle. For +instance, a `wave` decoration consists of arcs and the opening angle of +these arcs is given by the `angle`. + +This key sets the TeX-macro `\pgfdecorationsegmentangle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/angle", + meta = "⟨degree⟩" + }, + ["decoration/aspect"] = { + details = [[ +For some decorations there is a natural aspect ratio. For instance, for +a `brace` decoration the aspect ratio determines where the brace point +will be. + +This key sets the TeX-macro `\pgfdecorationsegmentaspect`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/aspect", + meta = "⟨factor⟩" + }, + ["decoration/closepath code"] = { + details = [[ +Set the code to be executed for every closepath input segment. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/closepath:code", + meta = "⟨code⟩" + }, + ["decoration/curveto code"] = { + details = [[ +Set the code to be executed for every curveto input segment. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/curveto:code", + meta = "⟨code⟩" + }, + ["decoration/end radius"] = { + details = [[ +For some decorations there is a natural end radius (of some circle, +presumably). + +This key stores the value directly inside the key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/end:radius", + meta = "⟨dimension⟩" + }, + ["decoration/foot angle"] = { + details = [[ +Footprints are rotated by this much. + + \begin{tikzpicture}[decoration={footprints,foot angle=60}] + \fill [decorate] (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/foot:angle" + }, + ["decoration/foot length"] = { + details = [[ +The length or size of the footprint itself. A larger value makes the +footprint larger, but does not change the stride length. + + \begin{tikzpicture}[decoration={footprints,foot length=20pt}] + \fill [decorate] (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/foot:length" + }, + ["decoration/foot of"] = { + details = [[ +The species whose footprints are shown. Possible values are: + + -------------------- ------------- + *Species* *Result* + `gnome` \[PICTURE\] + `human` \[PICTURE\] + `bird` \[PICTURE\] + `felis silvestris` \[PICTURE\] + -------------------- ------------- +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/foot:of" + }, + ["decoration/foot sep"] = { + details = [[ +The separation in the middle between the footprints. The footprints are +moved away from the path by half this amount. + + \begin{tikzpicture}[decoration={footprints,foot sep=10pt}] + \fill [decorate] (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/foot:sep" + }, + ["decoration/lineto code"] = { + details = [[ +Set the code to be executed for every lineto input segment. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/lineto:code", + meta = "⟨code⟩" + }, + ["decoration/mark"] = { + details = [[ +This works similarly to the `at position` version of this option, only +multiple marks are placed, starting at ⟨start pos⟩ and then spaced apart +by ⟨stepping⟩. The ⟨start pos⟩, the ⟨end pos⟩, and also the ⟨stepping⟩ +may all be specified in the same way as for the `at position` version, +that is, either using units or no units and also using positive or +negative values. + +Let us start with a simple example in which we place ten crosses along a +path starting with the beginning of the path ($⟨start pos⟩ = 0$) and +ending at the end ($⟨end pos⟩ = 1$). + + \begin{tikzpicture}[decoration={markings, + mark=between positions 0 and 1 step 0.1 + with { \draw (-2pt,-2pt) -- (2pt,2pt); + \draw (2pt,-2pt) -- (-2pt,2pt); }} ] + \draw [help lines] grid (3,2); + \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1); + \end{tikzpicture} + +In the next example we place arrow shapes on the path instead of +crosses. Note the use of the `transform shape` option to ensure that the +nodes are actually rotated. + + \begin{tikzpicture}[decoration={markings, + mark=between positions 0 and 1 step 1cm + with { \node [single arrow,fill=red, + single arrow head extend=3pt,transform shape] {};}}] + \draw [help lines] grid (3,2); + \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1); + \end{tikzpicture} + +Using the key `sequence number` we can also "number" the nodes and even +refer to them later on. + + \begin{tikzpicture}[decoration={markings, + mark=between positions 0 and 1 step 1cm with { + \node [draw, + name=mark-\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}, + transform shape] + {\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}};}}] + \draw [help lines] grid (3,2); + \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1); + \draw [red,->] (mark-3) -- (mark-7); + \end{tikzpicture} + +In the following example we use the distance info to place "length +information" on a path: + + \begin{tikzpicture}[decoration={markings, + % Main marks + mark=between positions 0 and 1 step 40pt with + { \draw [help lines] (0,0) -- (0,0.5) + node[above,font=\tiny]{ + \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; }, + mark=at position -0.1pt with + { \draw [help lines] (0,0) -- (0,0.5) + node[above,font=\tiny]{ + \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; }}] + \draw [help lines] grid (5,3); + \draw [postaction={decorate}] (0,0) .. controls (8,3) and (0,3) .. (5,0) ; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/mark", + meta = "between positions ⟨start pos⟩ and ⟨end pos⟩ step ⟨stepping⟩ with ⟨code⟩" + }, + ["decoration/mark connection node"] = { + details = [[ +When this key is set to a non-empty ⟨node name⟩ while the decoration is +being processed, the following happens: The marking code should, among +possibly other things, define a node named ⟨node name⟩. Then, the output +path of this decoration will contain a line-to to "one end" of this +node, followed by a moveto to the "other end" of the node. More +precisely, the first end is given by the position on the border of ⟨node +name⟩ that lies in the direction "from which the path heads toward the +node" while the other end lies on the border "where the path heads away +from the node". Furthermore, this option causes the decoration to end +with a line-to to the end instead of a move-to. + +The net effect of all this is that when you decorate a straight line +with one or more markings that contain just a node, the line will +effectively connect these nodes. + +Here are two examples that show how this works: + + \begin{tikzpicture}[decoration={markings, + mark connection node=my node, + mark=at position .5 with + {\node [draw,blue,transform shape] (my node) {my node};}}] + \draw [help lines] grid (3,2); + \draw decorate { (0,0) -- (3,2) }; + \end{tikzpicture} + + \begin{tikzpicture}[decoration={markings, + mark connection node=my node, + mark=at position .25 with + {\node [draw,red] (my node) {my node};}}] + \draw [help lines] grid (3,2); + \draw decorate { (0,0) -- (3,2) }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/mark:connection:node", + meta = "⟨node name⟩" + }, + ["decoration/mark info/distance from start"] = { + details = [[ +This key can only be read. Its value is the distance of the marking from +the start of the path in points. For instance, if the path length is +100pt and the marking is in the middle of the path, the value of this +key would be `50.0pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/mark:info/distance:from:start" + }, + ["decoration/mark info/sequence number"] = { + details = [[ +This key can only be read. Its value (which can be obtained using the +`\pgfkeysvalueof` command) is a "sequence number" of the mark. The first +mark that is added to a path has number `1`, the second number `2`, and +so on. This key is mainly useful in conjunction with repeated markings +(see below). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/mark:info/sequence:number" + }, + ["decoration/meta-amplitude"] = { + details = [[ +This key determines the amplitude for a meta-decoration. + +The key sets the TeX-macro (!) `\pgfmetadecorationsegmentamplitude`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/meta-amplitude", + meta = "⟨dimension⟩" + }, + ["decoration/meta-segment length"] = { + details = [[ +This determined the length of the meta-segments from which a +meta-decoration is made up. + +This key sets the TeX-macro (!) `\pgfmetadecorationsegmentlength`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/meta-segment:length", + meta = "⟨dimension⟩" + }, + ["decoration/mirror"] = { + details = [[ +Causes the segments of the decoration to be mirrored along the +to-be-decorated path. This is done after and in addition to any +transformations set using the `transform` and/or `raise` options. + + \begin{tikzpicture} + \node (a) {A}; + \node (b) at (2,1) {B}; + \draw (a) -- (b); + \draw[decorate,decoration=brace] (a) -- (b); + \draw[decorate,decoration={brace,mirror},red] (a) -- (b); + \draw[decorate,decoration={brace,mirror,raise=5pt},blue] (a) -- (b); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/mirror", + meta = "⟨boolean⟩" + }, + ["decoration/moveto code"] = { + details = [[ +Set the code to be executed for every moveto input segment. It is +important to remember that the transformations applied by the decoration +automaton are turned *off* when ⟨code⟩ is executed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/moveto:code", + meta = "⟨code⟩" + }, + ["decoration/name"] = { + details = [[ +Use this key to set which decoration is to be used. The ⟨name⟩ can both +be a decoration or a meta-decoration (you need to worry about the +difference only if you wish to define your own decorations). + +If you set ⟨name⟩ to `none`, no decorations are added. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw decorate [decoration={name=zigzag}] + { (0,0) .. controls (0,2) and (3,0) .. (3,2) }; + \end{tikzpicture} + +Since this option is used so often, you can also leave out the `name=` +part. Thus, the above example can be rewritten more succinctly: + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw decorate [decoration=zigzag] + { (0,0) .. controls (0,2) and (3,0) .. (3,2) }; + \end{tikzpicture} + +In general, when ⟨decoration options⟩ are parsed, for each unknown key +it is checked whether that key happens to be a (meta-)decoration and, if +so, the `name` option is executed for this key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/name", + meta = "⟨name⟩" + }, + ["decoration/path has corners"] = { + details = [[ +This is a hint to the decoration code as to whether the path has corners +or not. If a path has a sharp corner, setting this option to `true` may +result in better rendering of the decoration because the joins of input +segments are approached "more carefully" than when this key is set to +false. However, if the path is, say, a smooth circle, setting this key +to `true` will usually look worse. Most decorations ignore this key, +anyway. Internally, it sets the TeX-if `\ifpgfdecoratepathhascorners`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/path:has:corners", + meta = "⟨boolean⟩" + }, + ["decoration/pre"] = { + details = [[ +This key sets a decoration that should be used before the main +decoration starts. The ⟨decoration⟩ will be used for a length of +`pre length`, which `0pt` by default. Thus, for the `pre` option to have +any effect, you also need to set the `pre length` option. + + \tikz [decoration={zigzag,pre=lineto,pre length=1cm}] + \draw [decorate] (0,0) -- (2,1) arc (90:0:1); + + \tikz [decoration={zigzag,pre=moveto,pre length=1cm}] + \draw [decorate] (0,0) -- (2,1) arc (90:0:1); + + \tikz [decoration={zigzag,pre=crosses,pre length=1cm}] + \draw [decorate] (0,0) -- (2,1) arc (90:0:1); + +Note that the default `pre` option is `lineto`, not `curveto`. This +means that the default `pre` decoration will not follow curves (for +efficiency reasons). Change the `pre` key to `curveto` if you have a +curved path. + + \tikz [decoration={zigzag,pre length=3cm}] + \draw [decorate] (0,0) -- (2,1) arc (90:0:1); + + \tikz [decoration={zigzag,pre=curveto,pre length=3cm}] + \draw [decorate] (0,0) -- (2,1) arc (90:0:1); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/pre", + meta = "⟨decoration⟩" + }, + ["decoration/pre length"] = { + details = [[ +This key sets the distance along which the pre-decoration should be +used. If you do not need/wish a pre-decoration, set this key to `0pt` +(exactly this string, not just to something that evaluates to the same +things such as `0cm`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/pre:length", + meta = "⟨dimension⟩" + }, + ["decoration/radius"] = { + details = [[ +Sets the start and end radius simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/radius", + meta = "⟨dimension⟩" + }, + ["decoration/raise"] = { + details = [[ +The segments of the decoration are raised by ⟨dimension⟩ relative to the +to-be-decorated path. More precisely, the segments of the path are +offset by this much "to the left" of the path as we travel along the +path. This raising is done after and in addition to any transformations +set using the `transform` option (see below). + +A negative ⟨dimension⟩ will offset the decoration "to the right" of the +to-be-decorated path. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + + \draw (0,0) -- (1,1) arc (90:0:2 and 1); + \draw decorate [decoration=crosses] + { (0,0) -- (1,1) arc (90:0:2 and 1) }; + \draw[red] decorate [decoration={crosses,raise=5pt}] + { (0,0) -- (1,1) arc (90:0:2 and 1) }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/raise", + meta = "⟨dimension⟩" + }, + ["decoration/reset marks"] = { + details = [[ +Since `mark` options accumulate, there needs to be a way to "reset" +things, so that any `mark` options set in an enclosing scope do not +interfere. This option does exactly this. Note that when the ⟨code⟩ of a +marking is executed, the markings are automatically reset. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/reset:marks" + }, + ["decoration/reverse path"] = { + details = [[ +This key reverses the path. This is especially useful for typesetting +text along different sides of curves. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw [gray, ->] + [postaction={decoration={text along path, + text={a big juicy apple}, text color=red}, decorate}] + [postaction={decoration={text along path, + text={a big juicy apple}, text color=blue, reverse path}, decorate}] + (3,0) .. controls (3,2) and (0,2) .. (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/reverse:path", + meta = "⟨boolean⟩" + }, + ["decoration/segment length"] = { + details = [[ +Many decorations are made up of small segments. This key determines the +desired length of such segments. + +This key sets the TeX-dimension `\pgfdecorationsegmentlength`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/segment:length", + meta = "⟨dimension⟩" + }, + ["decoration/shape"] = { + details = [[ +The shape whose background path is used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape", + meta = "⟨shape name⟩" + }, + ["decoration/shape end height"] = { + details = [[ +The recommended ending height of the shape. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:end:height", + meta = "⟨length⟩" + }, + ["decoration/shape end size"] = { + details = [[ +Set both the end height and end width simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:end:size", + meta = "⟨length⟩" + }, + ["decoration/shape end width"] = { + details = [[ +The recommended ending width of the shape. Note that this is the width +that a shape will take only if it is drawn exactly at the end of the +path. + + \tikzset{ + bigger/.style={decoration={shape start size=.25cm, shape end size=1cm}}, + smaller/.style={decoration={shape start size=1cm, shape end size=.25cm}}, + decoration={shape backgrounds, + shape sep={.25cm, between borders},shape scaled} + } + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \fill [decorate,bigger, + decoration={shape sep={.25cm, between borders}}, blue!50] + (0,1.5) -- (3,1.5); + \fill [decorate,smaller, + decoration={shape sep={1cm, between centers}}, red!50] + (0,.5) -- (3,.5); + \draw [gray, dotted] (0,1.625) -- (3,2) (0,1.375) -- (3,1) + (0,1) -- (3,.625) (0,0) -- (3,.375); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:end:width", + meta = "⟨length⟩" + }, + ["decoration/shape evenly spread"] = { + details = [[ +This key overrides the `shape sep` key and forces the decoration to fit +⟨number⟩ shapes evenly across the path. If ⟨number⟩ is less than `1`, +then no shapes will be used. If ⟨number⟩ equals `1`, then one shape is +put in the middle of the path. The additional keywords `by centers` (the +default, if no keyword is specified) and `by borders` can be used (both +preceded by a comma), to specify how the distance between shapes is +determined. These keywords will only have a noticeable effect if the +shapes sizes differ over time. + + \tikzset{ + paint/.style={draw=#1!50!black, fill=#1!50}, + spreading/.style={ + decorate,decoration={shape backgrounds, shape=rectangle, + shape start size=4mm,shape end size=1mm,shape evenly spread={#1}}} + } + \begin{tikzpicture} + \fill [paint=green,spreading={5, by borders}, + decoration={shape scaled}] (0,2) -- (3,2); + \fill [paint=blue,spreading={5, by centers}, + decoration={shape scaled}] (0,1.5) -- (3,1.5); + \fill [paint=red, spreading=5] (0,1) -- (3,1); + \fill [paint=orange, spreading=4] (0,.5) -- (3,.5); + \fill [paint=gray, spreading=1] (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:evenly:spread", + meta = "⟨number⟩" + }, + ["decoration/shape height"] = { + details = [[ +Works like the previous key, only for the height. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:height", + meta = "⟨dimension⟩" + }, + ["decoration/shape scaled"] = { + details = [[ + \tikzset{ + bigger/.style={decoration={shape start size=.125cm, shape end size=.5cm}}, + smaller/.style={decoration={shape start size=.5cm, shape end size=.125cm}}, + decoration={shape backgrounds, + shape sep={.25cm, between borders},shape scaled} + } + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \fill [decorate, bigger, red!50] (0,1) -- (3,2); + \fill [decorate, smaller, blue!50] (0,0) -- (3,1); + \end{tikzpicture} + +If this key is set to false (which is the default), then only the start +width and height are used. Note that the keys `shape width` and +`shape height` set the start and end height simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:scaled", + meta = "⟨boolean⟩" + }, + ["decoration/shape sep"] = { + details = [[ +Set the spacing between the shapes on the decorations path. This can be +just a distance on its own, but the additional keywords +`between centers`, and `between borders` (which must be preceded by a +comma), specify that the distance is between the center anchors of the +shapes or between the edges of the *boundaries* of the shape borders. + + \begin{tikzpicture}[ + decoration={shape backgrounds,shape size=.5cm,shape=signal}, + signal from=west, signal to=east, + paint/.style={decorate, draw=#1!50!black, fill=#1!50}] + \draw [help lines] grid (3,2); + \draw [paint=red, decoration={shape sep=.5cm}] + (0,2) -- (3,2); + \draw [paint=green, decoration={shape sep={1cm, between centers}}] + (0,1) -- (3,1); + \draw [paint=blue, decoration={shape sep={1cm, between borders}}] + (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:sep", + meta = "⟨spacing⟩" + }, + ["decoration/shape size"] = { + details = [[ +Sets the desired width and height simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:size", + meta = "⟨dimension⟩" + }, + ["decoration/shape sloped"] = { + details = [[ +By default, shapes are rotated to the slope of the decorations path. If +⟨boolean⟩ is the value `false`, then this rotation is turned off. +Internally this sets the TeX-if `\ifpgfshapedecorationsloped` +accordingly. + + \tikzset{ + paint/.style={draw=#1!50!black, fill=#1!50} + } + \begin{tikzpicture}[decoration={ + shape width=.65cm, shape height=.45cm, + shape=isosceles triangle, shape sep=.75cm, + shape backgrounds}] + \draw [help lines] grid (3,2); + \draw [paint=red,decorate] (0,0) -- (2,2); + \draw [paint=blue,decorate,decoration={shape sloped=false}] + (1,0) -- (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:sloped", + meta = "⟨boolean⟩" + }, + ["decoration/shape start height"] = { + details = [[ +The starting height of the shape. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:start:height", + meta = "⟨length⟩" + }, + ["decoration/shape start size"] = { + details = [[ +Sets both the start height and start width simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:start:size", + meta = "⟨length⟩" + }, + ["decoration/shape start width"] = { + details = [[ +The starting width of the shape. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:start:width", + meta = "⟨length⟩" + }, + ["decoration/shape width"] = { + details = [[ +The desired width of the shapes. For decorations that support varying +shape sizes, this key sets both the start and end width (which can be +overwritten using options like `shape start width`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:width", + meta = "⟨dimension⟩" + }, + ["decoration/start radius"] = { + details = [[ +For some decorations there is a natural start radius (of some circle, +presumably). + +This key stores the value directly inside the key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/start:radius", + meta = "⟨dimension⟩" + }, + ["decoration/stride length"] = { + details = [[ +The length of strides. This is the distance between the beginnings of +left footprints along the path. + + \begin{tikzpicture}[decoration={footprints,stride length=50pt}] + \fill [decorate] (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/stride:length" + }, + ["decoration/text"] = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text", + meta = "⟨text⟩" + }, + ["decoration/text align"] = { + details = [[ +This changes the key path to `/pgf/decoration/text align` and executes +⟨alignment options⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align", + meta = "{⟨alignment options⟩}" + }, + ["decoration/text align/align"] = { + details = [[ +Aligns the text according to ⟨alignment⟩, which should be one of `left`, +`right`, or `center`. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw [red, dashed] + [postaction={decoration={text along path, text={a big juicy apple}, + text align={align=right}}, decorate}] + (0,0) .. controls (0,2) and (3,2) .. (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/align", + meta = "⟨alignment⟩" + }, + ["decoration/text align/center"] = { + details = [[ +Aligns the text to the center of the path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/center" + }, + ["decoration/text align/fit to path"] = { + details = [[ +This key makes the decoration automaton try to fit the text to the +length of the path. The automaton shifts forward by a small amount +between each character in order to fit the text to the path. If, +however, the length of the text is longer than the length of the path +(i.e., the automaton would have to shift *backwards* between characters) +this key will have no effect. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw [red, dashed] + [postaction={decoration={text along path, text={a big juicy apple}, + text align=fit to path}, decorate}] + (0,0) .. controls (0,2) and (3,2) .. (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/fit:to:path", + meta = "⟨boolean⟩" + }, + ["decoration/text align/fit to path stretching spaces"] = { + details = [[ +This key works like the previous key except the automaton shifts forward +only for space characters (including `\space`, but *excluding* `\`). + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw [red, dashed] + [postaction={decoration={text along path, text={a big juicy apple}, + text align={fit to path stretching spaces}}, decorate}] + (0,0) .. controls (0,2) and (3,2) .. (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/fit:to:path:stretching:spaces", + meta = "⟨boolean⟩" + }, + ["decoration/text align/left"] = { + details = [[ +Aligns the text to the left end of the path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/left" + }, + ["decoration/text align/left indent"] = { + details = [[ +Specifies a distance which the automaton should move along before it +starts typesetting the text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/left:indent", + meta = "⟨length⟩" + }, + ["decoration/text align/right"] = { + details = [[ +Aligns the text to the right end of the path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/right" + }, + ["decoration/text align/right indent"] = { + details = [[ +Specifies a distance before the end of the path, where the automaton +should stop typesetting the text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/right:indent", + meta = "⟨length⟩" + }, + ["decoration/text color"] = { + details = [[ +The color of the text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:color", + meta = "⟨color⟩" + }, + ["decoration/text effects/character command"] = { + details = [[ +This key specifies a command that is executed when each character is +placed in the node. The ⟨macro⟩ should be an ordinary TeX macro which +takes one argument. The argument will be a macro which when expanded +will contain the current character. + + \def\mycommand#1{#1$_\n$} + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, group letters, + word count=\n, + every word/.style={character command=\mycommand}, + characters={text along path}}] + + \path [decorate] (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/character:command", + meta = "⟨macro⟩" + }, + ["decoration/text effects/character count"] = { + details = [[ +Store the number of the character being typeset in ⟨macro⟩. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, + character count=\i, every word separator/.style={fill=red!30}, + characters={text along path, shape=circle, fill=gray!50}}] + + \path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/character:count", + meta = "⟨macro⟩" + }, + ["decoration/text effects/character total"] = { + details = [[ +Store the total number of the characters in the decoration text in +⟨macro⟩. This key can be used with the `character count` key to produce +some quite pleasing effects: + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + character count=\i, character total=\n, + characters={text along path, evaluate={\c=\i/\n*100;}, + text=orange!\c!blue, scale=\i/\n+0.5}}] + + \path [decorate] + (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/character:total", + meta = "⟨macro⟩" + }, + ["decoration/text effects/character widths"] = { + details = [[ +Shorthand for the `every character width` style. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, text align=center, + text effects/.cd, + character count=\i, + characters={xslant=0.5, text along path, name=c-\i}}] + + \path [decorate] (0,0) -- (3,2); + \path [decorate, + text effects={character widths={inner xsep=0pt, xslant=0}}] + (0,1) -- (3,3); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/character:widths", + meta = "{effects}" + }, + ["decoration/text effects/character ⟨number⟩"] = { + details = [[ +Specify additional effects for the character ⟨number⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/character:⟨number⟩" + }, + ["decoration/text effects/characters"] = { + details = [[ +Shorthand for the `every character`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/characters", + meta = "{effects}" + }, + ["decoration/text effects/every character"] = { + details = [[ +Set the effects that will be applied to every character in the +decoration text. The effects will typically be TikZ node options. +Initially, this style is empty so the decoration simply positions nodes +at the appropriate position along the path. In order to make the text +'follow the path' like the `text along path` decoration the following +key can be added to the `every character` style. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:character" + }, + ["decoration/text effects/every character width"] = { + details = [[ +This style is applied to the (invisible) nodes used for calculating the +width of a character node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:character:width" + }, + ["decoration/text effects/every first letter"] = { + details = [[ +Specify additional effects for the first letter in *every* word. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:first:letter" + }, + ["decoration/text effects/every last letter"] = { + details = [[ +Specify additional effects for the last letter in *every* word. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:last:letter" + }, + ["decoration/text effects/every letter"] = { + details = [[ +Specify additional effects for every letter (i.e., every character that +isn't the word separator) in the decoration text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:letter" + }, + ["decoration/text effects/every word"] = { + details = [[ +Specify additional effects for every word in the decoration text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:word" + }, + ["decoration/text effects/every word separator"] = { + details = [[ +Specify additional effects for every character that is a word separator. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:word:separator" + }, + ["decoration/text effects/fit text to path"] = { + details = [[ +This key will make the decoration increase the space between characters +so that the entire path is used by the decoration. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/every character/.style={text along path}}] + + \path [draw=gray, postaction={decorate}, rotate=90] + (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1); + \path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm, + text effects={fit text to path}] + (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/fit:text:to:path", + meta = "⟨true or false⟩" + }, + ["decoration/text effects/group letters"] = { + details = [[ +Group sequences of letters together so they are treated as a single +'character'. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, + every word separator/.style={fill=none}, + character count=\i, character total=\n, + characters={text along path, fill=gray!50, scale=\i/\n+0.5}}] + + \path [decorate] (0,0); + \path [decorate, text effects={group letters, + characters/.append={fill=red!20}}] + (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/group:letters" + }, + ["decoration/text effects/letter count"] = { + details = [[ +Store the number of letter being typeset (i.e., the position of the +character in the word) in ⟨macro⟩. Numbering starts at `1` and the +character acting as a word separator is numbered `0`. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, letter count=\i, every word separator/.style={fill=red!30}, + characters={text along path, shape=circle, fill=gray!50}}] + + \path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/letter:count", + meta = "⟨macro⟩" + }, + ["decoration/text effects/letter ⟨number⟩"] = { + details = [[ +Specify the effects for letter ⟨number⟩ in *every* word. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/letter:⟨number⟩" + }, + ["decoration/text effects/path from text"] = { + details = [[ +When this key is set to `true` and the decorated path consists only of a +single point, the decoration will calculate the width of the decoration +text using all the specified parameters as if the decorated path was +actually a straight line starting from the given point. This 'virtual' +straight line is then decorated with the text. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, + character count=\i, character total=\n, + characters={text along path, scale=\i/\n+0.5}}] + + \path [decorate] (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/path:from:text", + meta = "{true or false}" + }, + ["decoration/text effects/path from text angle"] = { + details = [[ +When used in conjunction with the `path from text` key, the straight +line that is used as the decorated path is rotated by ⟨angle⟩ around the +starting point. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, + character count=\i, character total=\n, + characters={text along path, scale=\i/\n+0.5}}] + + \path [decorate] (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/path:from:text:angle", + meta = "⟨angle⟩" + }, + ["decoration/text effects/repeat text"] = { + details = [[ +Usually, when the decoration runs out of text, it simply stops. This key +will make the decoration repeat the decoration text for the specified +number of ⟨times⟩. If no value is given the text will be repeated until +the path is finished. There are two points to remember however. Firstly +the numbering of characters, letters and words will be restarted each +time the text is repeated. Secondly, the options for alignment, scaling +or fitting the text to the path, fitting the path to the text, and so +on, are computed using the decoration text before the decoration starts. +If any of these options are given the behavior of the `repeat text` key +is undefined, but typically it will be ignored. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!\ }, + text effects/.cd, + repeat text, + character count=\m, character total=\n, + characters={text along path, scale=0.5+\m/\n/2}}] + + \path [draw=gray, ultra thin, postaction=decorate] + (180:2) \foreach \a in {0,...,12}{ arc (180-\a*90:90-\a*90:1.5-\a/10) }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/repeat:text", + meta = "⟨times⟩" + }, + ["decoration/text effects/replace characters"] = { + details = [[ +Replace the node for each character in ⟨characters⟩ with ⟨code⟩. The +⟨code⟩ can be thought of as describing a little picture or marking which +will be used instead of the character node. The origin will be the +current point along the decoration path. Any transformations associated +with the ⟨characters⟩ (e.g., applied with the `every character` or +`every letter` styles) will also be applied to ⟨code⟩. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, + replace characters=e with {\fill [red!20] (0,1mm) circle [radius=1mm];}, + replace characters=a with {\fill [black!20] (0,1mm) circle [radius=1mm];}, + character count=\i, character total=\n, + characters={text along path, scale=\i/\n+0.5}}] + + \path [decorate] (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/replace:characters", + meta = "⟨characters⟩ with {code}" + }, + ["decoration/text effects/reverse text"] = { + details = [[ +Reverse the order of the characters in the decoration text. This may be +useful if using 'right-to-left' languages. Unfortunately, any leading +'soft' spaces in the original text will be lost. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, + reverse text, + character count=\i, character total=\n, + characters={text along path, scale=\i/\n+0.5}}] + + \path [decorate] (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2); + \end{tikzpicture} + +It is important to note that the `reverse text` key reverses the text +*before* doing anything else. This means that the numbering of +characters, letters and words will still be in the normal order, so any +parameterized effects will have to take this into account. +Alternatively, to get the numbering to follow the reversed text, it is +possible to reverse the path and then invert the scale: + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, + character count=\i, character total=\n, + characters={text along path, scale=\i/\n+0.5}}] + + \path [decorate, text effects={reverse text}] (0,0); + \path [blue, decorate, decoration={reverse path}, + text effects={characters/.append={scale=-1}}] (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/reverse:text" + }, + ["decoration/text effects/scale text to path"] = { + details = [[ +This key will make the decoration scale the text so that the entire path +is used by the decoration. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/every character/.style={text along path}}] + + \path [draw=gray, postaction={decorate}, rotate=90] + (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1); + \path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm, + text effects={scale text to path}] + (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/scale:text:to:path", + meta = "⟨true or false⟩" + }, + ["decoration/text effects/style characters"] = { + details = [[ +This key enables ⟨effects⟩ to be applied to every character in the +decoration text that is specified in ⟨characters⟩. + + \begin{tikzpicture}[decoration={text effects along path, + text={Falsches {\"U}ben von Xylophonmusik qu{\"a}lt jeden gr{\"o}{\ss}eren Zwerg}, + text effects/.cd, + path from text, + style characters=aeiou{\"U}{\"a}{\"o} with {text=blue}, + characters={text along path}}] + + \path [decorate] (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/style:characters", + meta = "{characters} with {effects}" + }, + ["decoration/text effects/text along path"] = { + details = [[ +This style automatically sets the TikZ keys `transform shape` (to make +the character slope with the path), `anchor=baseline` (to make the +baseline of the characters 'sit' on the path) and `inner xsep=0pt` (to +horizontally fit each node to the character it contains, reducing the +spacing between characters). + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}}] + + \path [draw=red, dotted, postaction={decorate}] + (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2); + \path [draw=blue, dotted, yshift=1cm, postaction={decorate}, + text effects={text along path}] + (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/text:along:path" + }, + ["decoration/text effects/word count"] = { + details = [[ +Store the number of words in the decoration text in ⟨macro⟩. Numbering +starts at `1`. When the character is the word separator, ⟨macro⟩ takes +the number of the previous word. If the decoration text starts with a +word separator ⟨macro⟩ will be `0`. + + \begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, word count=\i, every word separator/.style={fill=red!30}, + characters={text along path, shape=circle, fill=gray!50}}] + + \path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/word:count", + meta = "⟨macro⟩" + }, + ["decoration/text effects/word separator"] = { + details = [[ +Specify the character that is to be used as the word separator. This +*must* be a single character such as `a` or `-` or the special value +`space` (which should be used to indicate that spaces should be used as +the separator). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/word:separator", + meta = "⟨character⟩" + }, + ["decoration/text effects/word total"] = { + details = [[ +Store the total number of words in the decoration text in ⟨macro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/word:total", + meta = "⟨macro⟩" + }, + ["decoration/text effects/word ⟨m⟩ letter ⟨n⟩"] = { + details = [[ +Specify additional effects for letter ⟨n⟩ in word ⟨m⟩ in the decoration +text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/word:⟨m⟩:letter:⟨n⟩" + }, + ["decoration/text effects/word ⟨number⟩"] = { + details = [[ +Specify additional effects for word ⟨number⟩ in the decoration text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/word:⟨number⟩" + }, + ["decoration/text format delimiters"] = { + details = [[ +' +texttt + +13 + +Set the characters that the text decoration will use to parse formatting +commands. If \\meta{after} is empty, then \\meta{before} will be used +for both delimiters. In general you should stick to characters whose +category codes are + +11` or `12`. As `+` is used to indicate that the specified format commands are added to any existing ones, you should avoid using `+| +as a delimiter. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \path [decorate, decoration={text along path,text format delimiters={[}{]}, + text={A big [\color{red}]red[] and [\color{green}]green[] apple.}}] + (0,0) .. controls (0,2) and (3,0) .. (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:format:delimiters", + meta = "{before}{after}" + }, + ["decoration/text/effetcs/letter total"] = { + details = [[ +Store the number of letters in the current word in ⟨macro⟩. When the +character is the word separator, this value is `0`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text/effetcs/letter:total", + meta = "⟨macro⟩" + }, + ["decoration/transform"] = { + details = [[ +This key allows you to specify general ⟨transformations⟩ to be applied +to the segments of a decoration. These transformations are applied +before and independently of `raise` and `mirror` transformations. The +⟨transformations⟩ should be normal TikZ transformations like `shift` or +`rotate`. + +In the following example the `shift only` transformation is used to make +sure that the crosses are *not* sloped along the path. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + + \draw (0,0) -- (1,1) arc (90:0:2 and 1); + \draw[red,very thick] decorate [decoration={ + crosses,transform={shift only},shape size=1.5mm}] + { (0,0) -- (1,1) arc (90:0:2 and 1) }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/transform", + meta = "⟨transformations⟩" + }, + ["decorations/post"] = { + details = [[ +Works like `pre`, only for the end of the decoration. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decorations/post", + meta = "⟨decoration⟩" + }, + ["decorations/post length"] = { + details = [[ +Works like `pre length`, only for the end of the decoration. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decorations/post:length", + meta = "⟨dimension⟩" + }, + ["direction ee arrow"] = { + details = [[ +The value of this key will be used for the arrow tip depicted in an +`direction ee` shape. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/direction:ee:arrow", + meta = "⟨right arrow tip name⟩" + }, + ["double arrow head extend"] = { + details = [[ +This sets the distance between the shaft of the arrow and the outer end +of the arrow heads. This may change if the shape is enlarged to some +minimum width. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/double:arrow:head:extend", + meta = "⟨length⟩" + }, + ["double arrow head indent"] = { + details = [[ +This moves the point where the arrow heads join the shaft of the arrow +*towards* the arrow tips, by ⟨length⟩. + + \begin{tikzpicture}[every node/.style={double arrow, draw=none, rotate=-60}] + \node [fill=red!50] {arrow 1}; + \node [fill=blue!50, double arrow head indent=1ex] at (1.5,0) {arrow 2}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/double:arrow:head:indent", + meta = "⟨length⟩" + }, + ["double arrow tip angle"] = { + details = [[ +Sets the angle for the arrow tip. Enlarging the arrow to some minimum +width may increase the height of the shape to maintain this angle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/double:arrow:tip:angle", + meta = "⟨angle⟩" + }, + ["every data"] = { + details = [[ +This style is executed by `\pgfdata` before the ⟨options⟩ are parsed. + +Note that the path of this key is just `/pgf/`, not `/pgf/data/`. Also +note that TikZ internally sets the value of this key up in such a way +that the keys `/tikz/every data` and also +`/tikz/data visualization/every data` are executed. The bottom line of +this is that when using TikZ, you should not set this key directly, set +`/tikz/every data` instead. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/every:data" + }, + ["every decoration"] = { + details = [[ +This style is executed for every decoration. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/every:decoration" + }, + ["fixed point arithmetic"] = { + details = [[ +This key will set the key path to `/pgf/fixed point`, and execute +⟨options⟩. Then it will install the necessary commands so that the PGF +parser will use `fp` to perform calculations. The best way to use this +key is as an argument to a scope or picture. This means that `fp` does +not always have to be used, and PGF can use its own mathematical engine +at other times, which can lead to a significant reduction in the time +for a document to compile. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fixed:point:arithmetic", + meta = "⟨options⟩" + }, + ["fixed point/scale file plot x"] = { + details = [[ +This key will scale the first column of data read from a file before it +is plotted. It is independent of the `scale results` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fixed:point/scale:file:plot:x", + meta = "⟨factor⟩" + }, + ["fixed point/scale file plot y"] = { + details = [[ +This key will scale the second column of data read from a file before it +is plotted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fixed:point/scale:file:plot:y", + meta = "⟨factor⟩" + }, + ["fixed point/scale file plot z"] = { + details = [[ +This key will scale the third column of data read from a file before it +is plotted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fixed:point/scale:file:plot:z", + meta = "⟨factor⟩" + }, + ["fixed point/scale results"] = { + details = [[ +As noted above, `fp` can process a far greater range of numbers than PGF +and TikZ. In order to use results from `fp` in a `{pgfpicture}` or a +`{tikzpicture}` they need to be scaled. When this key is used PGF will +scale results of any evaluation by ⟨factor⟩. However, as it is not +desirable for every part of every expression to be scaled, scaling will +only take place if a special prefix `*` is used. If `*` is used at the +beginning of an expression the evaluation of the expression will +evaluated and then multiplied by ⟨factor⟩. + + \begin{tikzpicture}[fixed point arithmetic={scale results=10^-6}] + \draw [help lines] grid (3,2); + \draw (0,0) -- (2,2); + \draw [red, line width=4pt] (*1.0e6,0) -- (*3.0e6,*2.0e6); + \end{tikzpicture} + +A special case of scaling involves plots of data containing large +numbers from files. It is possible to "pre-process" a file, typically +using the application that generates the data, to either precede the +relevant column with `*` or to perform the scaling as part of the +calculation process. However, it may be desirable for the data in a plot +to appear in a table as well, so, two files would be required, one +pre-processed for plotting, and one not. This extra work may be +undesirable so the following keys are provided: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fixed:point/scale:results", + meta = "⟨factor⟩" + }, + ["foreach/count"] = { + details = [[ +This key allows ⟨macro⟩ to hold the position in the list of the current +item. The optional `from `⟨value⟩ statement allows the counting to begin +from ⟨value⟩. + + \tikz[x=0.75cm,y=0.75cm] + \foreach \x [count=\xi] in {a,...,e} + \foreach \y [count=\yi] in {\x,...,e} + \node [draw, top color=white, bottom color=blue!50, minimum size=0.666cm] + at (\xi,-\yi) {$\mathstrut\x\y$}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/count", + meta = "⟨macro⟩ from ⟨value⟩" + }, + ["foreach/evaluate"] = { + details = [[ +By default, list items are not evaluated: `1+2`, yields `1+2`, not `3`. +This key allows a variable to be evaluated using the mathematical +engine. The variable must have been specified either using the `var` key +or in the ⟨variables⟩ argument of the `foreach` command. By default, the +result of the evaluation will be stored in ⟨variable⟩. However, the +optional `as `⟨macro⟩ statement can be used to store the result in +⟨macro⟩. + + \foreach \x [evaluate=\x] in {2^0,2^...,2^8}{$\x$, } + + \foreach \x [evaluate=\x as \xeval] in {2^0,2^...,2^8}{$\x=\xeval$, } + +The optional `using `⟨formula⟩ statement means an evaluation does not +have to be explicitly stated for each item in ⟨list⟩. The ⟨formula⟩ +should contain at least one reference to ⟨variable⟩. + + \tikz\foreach \x [evaluate=\x as \shade using \x*10] in {0,1,...,10} + \node [fill=red!\shade!yellow, minimum size=0.65cm] at (\x,0) {\x}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/evaluate", + meta = "⟨variable⟩ as ⟨macro⟩ using ⟨formula⟩" + }, + ["foreach/expand list"] = { + details = [[ +If this key is set to true the contents of the list are fully expanded +with `\edef` before further processing. This allows using complex macros +which generate a list upon expansion without having to use an +intermediate macro. + + \def\Iota#1#2{% + \ifnum\numexpr#1\relax<\numexpr#2\relax + \the\numexpr#1\relax,% + \expandafter\Iota\expandafter{\the\numexpr(#1)+1\relax}{#2}% + \else + \the\numexpr#2\relax + \fi} + \foreach [expand list=true] \x in {\Iota{1}{5}} { + \x + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/expand:list", + meta = "{boolean}" + }, + ["foreach/parse"] = { + details = [[ +If this key is set to true the upper bound in the loop will be fed into +`\pgfmathparse`. This allows to use complex expressions as the upper +bound. However, the expression must be safe for evaluation in +`\pgfmathparse`. It is known that internal TeX registers can cause +trouble. + + \foreach \x [parse=true] in {1,...,1.0e+1 - 1}{ \x } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/parse", + meta = "{boolean}" + }, + ["foreach/remember"] = { + details = [[ +This key allows the item value stored in ⟨variable⟩ to be remembered +during the next iteration, stored in ⟨macro⟩. If a variable is +evaluated, the result of this evaluation is remembered. By default the +value of ⟨variable⟩ is zero for the first iteration, however, the +optional `(initially `⟨value⟩`)` statement, allows the ⟨macro⟩ to be +initially defined as ⟨value⟩. + + \foreach \x [remember=\x as \lastx (initially A)] in {B,...,H}{$\overrightarrow{\lastx\x}$, } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/remember", + meta = "⟨variable⟩ as ⟨macro⟩ (initially ⟨value⟩)" + }, + ["foreach/var"] = { + details = [[ +This key provides an alternative way to specify variables: +`\foreach [var=\x,var=\y]` is the same as `\foreach \x/\y`. If used, +this key should be used before the other keys. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/var", + meta = "⟨variable⟩" + }, + fpu = { + details = [[ +This key installs or uninstalls the FPU. The installation exchanges any +routines of the standard math parser with those of the FPU: +`\pgfmathadd` will be replaced with `\pgfmathfloatadd` and so on. +Furthermore, any number will be parsed with `\pgfmathfloatparsenumber`. + + \pgfkeys{/pgf/fpu} + \pgfmathparse{1+1}\pgfmathresult + +The FPU uses a low-level number representation consisting of flags, +mantissa and exponent [1]. To avoid unnecessary format conversions, +`\pgfmathresult` will usually contain such a cryptic number. Depending +on the context, the result may need to be converted into something which +is suitable for PGF processing (like coordinates) or may need to be +typeset. The FPU provides such methods as well. + +Use `fpu=false` to deactivate the FPU. This will restore any change. +Please note that this is not necessary if the FPU is used inside of a +TeX group -- it will be deactivated afterwards anyway. + +It does not hurt to call `fpu=true` or `fpu=false` multiple times. + +Please note that if the `fixedpointarithmetic` library of PGF will be +activated after the FPU, the FPU will be deactivated automatically. + +[1] Users should *always* use high level routines to manipulate floating +point numbers as the format may change in a future release. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu", + meta = "{boolean}" + }, + ["fpu/handlers/empty number"] = { + details = [[ +This command key is invoked in case an empty string is parsed inside of +`\pgfmathfloatparsenumber`. You can overwrite it to assign a replacement +`\pgfmathresult` (in float!). + +The initial setting is to invoke `invalid number`, see below. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/handlers/empty:number", + meta = "{input}{unreadable part}" + }, + ["fpu/handlers/invalid number"] = { + details = [[ +This command key is invoked in case an invalid string is parsed inside +of `\pgfmathfloatparsenumber`. You can overwrite it to assign a +replacement `\pgfmathresult` (in float!). + +The initial setting is to generate an error message. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/handlers/invalid:number", + meta = "{input}{unreadable part}" + }, + ["fpu/handlers/wrong lowlevel format"] = { + details = [[ +This command key is invoked whenever `\pgfmathfloattoregisters` or its +variants encounter something which is not a properly formatted low-level +floating point number. As for `invalid number`, this key may assign a +new `\pgfmathresult` (in floating point) which will be used instead of +the offending ⟨input⟩. + +The initial setting is to generate an error message. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/handlers/wrong:lowlevel:format", + meta = "{input}{unreadable part}" + }, + ["fpu/install only"] = { + details = [[ +\[fpu-install-only\] Unfortunately, the FPU is currently incompatible +with drawing operations. However, it can still be useful to replace +single definitions with FPU counterparts to avoid errors of the kind +`Dimension too large` which tend to happen when transformation matrices +are inverted. + +This key allows to specify a list of definitions to be pulled into the +current scope. *Note that there is no reverse operation to uninstall +these definitions at the moment*, so it is advisable to do this in a +group. Conveniently, TikZ paths form an implicit group, so you can use +this key on a path as well. + +You have to be aware of the limitations that the FPU imposes. It will +not magically give TeX better precision, but it will avoid overflow or +underflow situations for large or small operands by rescaling them. In +the following example, in the first case the FPU variant performs much +better than the normal variant, however, in the second case where a +rescaling would not in fact be needed the rescaling introduces a small +round-off error. + + \begingroup + \pgfkeys{/pgf/fpu/install only={divide}} + \pgfmathparse{12.34/0.001234}\pgfmathresult (good) + \pgfmathparse{12/4}\pgfmathresult (bad) + \endgroup + +This key is introduced in PGFv3.1.6 and marked stable since PGF v3.1.8. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/install:only", + meta = "{list of names}" + }, + ["fpu/output format"] = { + details = [[ +This key allows to change the number format in which the FPU assigns +`\pgfmathresult`. + +The predefined choice `float` uses the low-level format used by the FPU. +This is useful for further processing inside of any library. + + \pgfkeys{/pgf/fpu,/pgf/fpu/output format=float} + \pgfmathparse{exp(50)*42}\pgfmathresult + +The choice `sci` returns numbers in the format ⟨mantissa⟩`e`⟨exponent⟩. +It provides almost no computational overhead. + + \pgfkeys{/pgf/fpu,/pgf/fpu/output format=sci} + \pgfmathparse{4.22e-8^-2}\pgfmathresult + +The choice `fixed` returns normal fixed point numbers and provides the +highest compatibility with the PGF engine. It is activated automatically +in case the FPU scales results. + + \pgfkeys{/pgf/fpu,/pgf/fpu/output format=fixed} + \pgfmathparse{sqrt(1e-12)}\pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/output:format", + meta = "⟨float,sci,fixed⟩" + }, + ["fpu/rel thresh"] = { + details = [[ +A threshold used by `\pgfmathfloatifapproxequalrel` to decide whether +numbers are approximately equal. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/rel:thresh", + meta = "{number}" + }, + ["fpu/scale results"] = { + details = [[ +A feature which allows semi-automatic result scaling. Setting this key +has two effects: first, the output format for *any* computation will be +set to `fixed` (assuming results will be processed by PGF's kernel). +Second, any expression which starts with a star, `*`, will be multiplied +with ⟨scale⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/scale:results", + meta = "{scale}" + }, + ["gap around stream point"] = { + details = [[ +The ⟨dimension⟩ by which the lines between consecutive stream points are +shortened at the beginning and end. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/gap:around:stream:point", + meta = "⟨dimension⟩" + }, + ["generic circle IEC/before background"] = { + details = [[ +When a node of shape `generic circle IEC` is created, the current +setting of this key is used as the "before background path". This means +that after the circle's background has been drawn/filled/whatever, the +⟨code⟩ is executed. + +When the ⟨code⟩ is executed, the coordinate system will have been +transformed in such a way that the point $(1\mathrm{pt},0\mathrm{pt})$ +lies at the right end of the circle and $(0\mathrm{pt},1\mathrm{pt})$ +lies at the top of the circle. (More precisely, these points will lie +exactly on the middle of the radial line.) +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/generic:circle:IEC/before:background", + meta = "⟨code⟩" + }, + ["generic diode IEC/before background"] = { + details = [[ +Similarly to the `generic circle IEC` shape, when a node of shape +`generic diode IEC` is created, the current setting of this key is used +as the "before background path". When the ⟨code⟩ is executed, the +coordinate system will have been transformed in such a way that the +origin is at the "tip" of the diode's triangle, the point +$(0\mathrm{pt},1\mathrm{pt})$ is exactly half the diode's height above +this origin, and the point $(1\mathrm{pt},0\mathrm{pt})$ is half the +diode's height to the right of the origin. + +The idea is that you use this key to draw different kinds of diode +endings. + + \tikz \node [minimum size=1cm,generic diode IEC, + /pgf/generic diode IEC/before background={ + \pgfpathmoveto{\pgfqpoint{-.5pt}{-1pt}} + \pgfpathlineto{\pgfqpoint{.5pt}{-1pt}} + \pgfpathmoveto{\pgfqpoint{0pt}{-1pt}} + \pgfpathlineto{\pgfqpoint{0pt}{1pt}} + \pgfpathmoveto{\pgfqpoint{-.5pt}{1pt}} + \pgfpathlineto{\pgfqpoint{.5pt}{1pt}} + \pgfusepathqstroke + }, + draw] {}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/generic:diode:IEC/before:background", + meta = "⟨code⟩" + }, + ["handle new data sets in plots"] = { + details = [[ +You can set ⟨how⟩ to one of the following values: + +- `ignore` The command will be completely ignored, just as if the + command had not been used at all. + +- `jump` This causes the internal macro `\pgf@plotstreamjump` to be + called. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/handle:new:data:sets:in:plots", + meta = "⟨how⟩" + }, + ["handle outlier points in plots"] = { + details = [[ +You can set ⟨how⟩ to one of the following values: + +- `plot` This will cause the outlier to be drawn normally, just as if + `\pgfplotstreampoint` had been used rather than this command. + +- `ignore` The outlier will be completely ignored, just as if the + command had not been used at all. + +- `jump` This causes the internal macro `\pgf@plotstreamjump` to be + called. A "jump" in a stream is a position where a "gap" is + introduced. For instance, a simple line-to plot handler will stop + the current subpath at a jump position and begin with a move-to + operation at the next normal point of the stream. + + The net effect of this setting is that at outlier points plots get + interrupted and "restarted" when the points are no longer outliers. + This is usually the behavior you will be looking for. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/handle:outlier:points:in:plots", + meta = "⟨how⟩" + }, + ["handle undefined points in plots"] = { + details = [[ +You can set ⟨how⟩ to one of the following values: + +- `ignore` The undefined point will be completely ignored, just as if + the command had not been used at all. + +- `jump` This causes the internal macro `\pgf@plotstreamjump` to be + called. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/handle:undefined:points:in:plots", + meta = "⟨how⟩" + }, + ["images/external info"] = { + details = [[ +If this key is activated, the size for any externalized image will be +stored explicitly into the associated `.dpth` file. + +When the file is included by `\pgfincludeexternalgraphics` (or +automatically by the `external` library), the width is available as +`\pgfexternalwidth` and the height as `\pgfexternalheight`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/images/external:info", + meta = "{boolean}" + }, + ["images/include external"] = { + details = [[ +\[pgf:includeexternalkey\] This key constitutes the public interface to +exchange the `\includegraphics` command used for the image inclusion. + +Redefining this key allows to provide bounding box or viewport options: + + \pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}} + +Do not forget the `.code` here which redefines the command. + +One application could be image externalization and bounding box +restrictions: As far as I know, a `.pdf` graphics with restricted +bounding box is always cropped (which is not always desired). One +solution could be to use `latex` and `dvips` which doesn't have this +restriction. Another is to manually provide the `viewport` option as +shown above. + +A possible value for `viewport` can be found in the `.pdf` image, search +for `/MediaBox = [ ... ]`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/images/include:external" + }, + ["inner sep"] = { + details = [[ +This style sets both `/pgf/inner xsep` and `/pgf/inner ysep` to +⟨dimension⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/inner:sep", + meta = "⟨dimension⟩" + }, + ["inner xsep"] = { + details = [[ +This key stores the *recommended* horizontal inner separation between +the label text and the background path. As before, this value is just a +recommendation and a shape may choose to ignore this key. + + \begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfset{inner xsep=1cm} + \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/inner:xsep", + meta = "⟨dimension⟩" + }, + ["inner ysep"] = { + details = [[ +Works like `/pgf/inner xsep`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/inner:ysep", + meta = "⟨dimension⟩" + }, + ["isosceles triangle apex angle"] = { + details = [[ +Sets the angle of the apex of the isosceles triangle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/isosceles:triangle:apex:angle", + meta = "⟨angle⟩" + }, + ["isosceles triangle stretches"] = { + details = [[ +By default ⟨boolean⟩ is `false`. This means, that when applying any +minimum width or minimum height requirements, increasing the height will +increase the width (and vice versa), in order to keep the apex angle the +same. + + \begin{tikzpicture}[paint/.style={draw=#1!75, fill=#1!20}] + \tikzset{every node/.style={isosceles triangle, draw, inner sep=0pt, + anchor=left corner, shape border rotate=90}} + \draw[help lines] grid(4,2); + \foreach \a/\c in {1.5/blue, 1/green, 0.5/red}{ + \node[paint=\c, minimum height=\a cm] at (0,0) {}; + \node[paint=\c, minimum width=\a cm] at (2,0) {}; + } + \end{tikzpicture} + +However, by setting ⟨boolean⟩ to `true`, minimum width and height can be +applied independently. + + \begin{tikzpicture}[paint/.style={draw=#1!75, fill=#1!20}] + \tikzset{every node/.style={isosceles triangle, draw, inner sep=0pt, + anchor=south, shape border rotate=90, isosceles triangle stretches}} + \draw[help lines] grid(4,2); + \foreach \a/\c in {1.5/blue, 1/green, 0.5/red}{ + \node[paint=\c, minimum height=\a cm, minimum width=1.5cm] at (0.75,0) {}; + \node[paint=\c, minimum width=\a cm, minimum height=1.5cm] at (3,0) {}; + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/isosceles:triangle:stretches", + meta = "⟨boolean⟩" + }, + ["key filter handlers/append filtered to"] = { + details = [[ +Install this filter handler to append any unprocessed options to macro +`{macro}`. + + \pgfkeys{/pgf/key filter handlers/append filtered to/.install key filter handler=\remainingoptions} + \def\remainingoptions{} + \pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, + /my group/B=b, /my group/C=c, /tikz/color=blue} + + Remaining options: `\remainingoptions'. + +This example uses the same keys as defined in the intro section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filter:handlers/append:filtered:to", + meta = "{macro}" + }, + ["key filter handlers/ignore"] = { + details = [[ +Install this filter handler if you simply want to ignore any unprocessed +option. This is the default. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filter:handlers/ignore" + }, + ["key filter handlers/log"] = { + details = [[ +This key filter handler writes messages for any unprocessed option to +your logfile (and terminal). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filter:handlers/log" + }, + ["key filters/active families"] = { + details = [[ +Install this key filter if `\pgfkeysfiltered` should only process +activated families. If a key does not belong to any family, it is not +processed. If a key is completely unknown within the default path, the +normal 'unknown' handlers of `\pgfkeys` are invoked. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/active:families" + }, + ["key filters/active families and known"] = { + details = [[ +A fast alias for + +`/pgf/key filters/active families or no family=` + +`{/pgf/keys filters/false}` + +`{/pgf/keys filters/false}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/active:families:and:known" + }, + ["key filters/active families or descendants of"] = { + details = [[ +A fast alias for + +`/pgf/key filters/active families or no family=` + +`{/pgf/keys filters/is descendant of=``{path prefix}``}` + +`{/pgf/keys filters/false}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/active:families:or:descendants:of", + meta = "{path prefix}" + }, + ["key filters/active families or no family"] = { + details = [[ +This key filter configures `\pgfkeysfiltered` to work as follows. + +1. If the current key belongs to a family, set + `\ifpgfkeysfiltercontinue` to true if and only if its family is + active. + +2. If the current key does *not* belong to a family, assign + `\ifpgfkeysfiltercontinue` as result of `{key filter 1}`. + +3. If the current key is unknown within the default path, assign + `\ifpgfkeysfiltercontinue` as result of `{key filter 2}`. + +The arguments `{key filter 1}` and `{key filter 2}` are other key +filters (possibly with options) and allow fine-grained control over the +filtering process. + + \pgfkeysinstallkeyfilter + {/pgf/key filters/active families or no family} + {{/pgf/key filters/is descendant of=/tikz}% for keys without family + {/pgf/key filters/false}% for unknown keys + }% + +This key filter will return true for any option with active family. If +an option has no family, the return value is true if and only if it +belongs to `/tikz`. If the option is unknown, the return value is +`false` and unknown handlers won't be called. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/active:families:or:no:family", + meta = "{key filter 1}{key filter 2}" + }, + ["key filters/active families or no family DEBUG"] = { + details = [[ +A variant of `active families or no family` which protocols each action +on your terminal (log-file). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/active:families:or:no:family:DEBUG", + meta = "{key filter 1}{key filter 2}" + }, + ["key filters/and"] = { + details = [[ +This key filter returns true if and only if both, `{key filter 1}` and +`{key filter 2}` return true. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/and", + meta = "{key filter 1}{key filter 2}" + }, + ["key filters/defined"] = { + details = [[ +This key filter returns false if the current key is unknown, which +avoids calling the unknown handlers. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/defined" + }, + ["key filters/equals"] = { + details = [[ +Install this key filter to process only the fully qualified option +`{full key}`. The filter returns true for any unknown key or if the key +equals `{full key}`. + + \pgfkeys{ + /group 1/A/.code={(A:#1)}, + /group 1/B/.code={(B:#1)}, + /pgf/key filters/equals/.install key filter=/group 1/A} + \pgfqkeysfiltered{/group 1}{A=a,B=b} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/equals", + meta = "{full key}" + }, + ["key filters/false"] = { + details = [[ +This key filter returns always false (including unknown keys). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/false" + }, + ["key filters/is descendant of"] = { + details = [[ +Install this key filter to process only options belonging to the key +tree ⟨path⟩. It returns true for every key whose key path is equal to +⟨path⟩. It also returns true for any unknown key, that means unknown +keys are processed using the standard unknown handlers of PGF. + + \pgfkeys{ + /group 1/A/.code={(A:#1)}, + /group 1/foo/bar/B/.code={(B:#1)}, + /group 2/C/.code={(C:#1)}, + /pgf/key filters/is descendant of/.install key filter=/group 1} + \pgfkeysfiltered{/group 1/A=a,/group 1/foo/bar/B=b,/group 2/C=c} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/is:descendant:of", + meta = "{path}" + }, + ["key filters/not"] = { + details = [[ +This key filter logically inverts the result of `{key filter}`. + + \pgfkeys{ + /group 1/A/.code={(A:#1)}, + /group 1/foo/bar/B/.code={(B:#1)}, + /group 2/C/.code={(C:#1)}, + /pgf/key filters/not/.install key filter= + {/pgf/key filters/is descendant of=/group 1}} + \pgfkeysfiltered{/group 1/A=a,/group 1/foo/bar/B=b,/group 2/C=c} + +Please note that unknown keys will be handed to the usual unknown +handlers. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/not", + meta = "{key filter}" + }, + ["key filters/or"] = { + details = [[ +This key filter returns true if one of `{key filter 1}` and +`{key filter 2}` returns true. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/or", + meta = "{key filter 1}{key filter 2}" + }, + ["key filters/true"] = { + details = [[ +This key filter returns always true. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/true" + }, + ["kite lower vertex angle"] = { + details = [[ +Sets the lower internal angle of the kite. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/kite:lower:vertex:angle", + meta = "⟨angle⟩" + }, + ["kite upper vertex angle"] = { + details = [[ +Sets the upper internal angle of the kite. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/kite:upper:vertex:angle", + meta = "⟨angle⟩" + }, + ["kite vertex angles"] = { + details = [[ +This key sets the keys for both the upper and lower vertex angles (it +stores no value itself). ⟨angle specification⟩ can be pair of angles in +the form ⟨upper angle⟩ `and` ⟨lower angle⟩, or a single angle. In this +latter case, both the upper and lower vertex angles will be the same. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/kite:vertex:angles", + meta = "⟨angle specification⟩" + }, + ["l-system"] = { + details = [[ +A more compact version of the previous key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/l-system", + meta = "{keys}" + }, + ["lindenmayer system"] = { + details = [[ +This key changes the key path to `/pgf/lindenmayer systems` and executes +⟨keys⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system", + meta = "{keys}" + }, + ["lindenmayer system/anchor"] = { + details = [[ +Be default, when this key is not used, the L-system will start from the +last specified coordinate. By using this key, the L-system will be +placed inside a special (rectangle) node which can be positioned using +⟨anchor⟩. + + \begin{tikzpicture}[l-system={step=1.75pt, order=5, angle=60}] + \pgfdeclarelindenmayersystem{Sierpinski triangle}{ + \symbol{X}{\pgflsystemdrawforward} + \symbol{Y}{\pgflsystemdrawforward} + \rule{X -> Y-X-Y} + \rule{Y -> X+Y+X} + } + \draw [help lines] grid (3,2); + \draw [red] (0,0) l-system + [l-system={Sierpinski triangle, axiom=+++X, anchor=south west}]; + \draw [blue] (3,2) l-system + [l-system={Sierpinski triangle, axiom=X, anchor=north east}]; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/anchor", + meta = "⟨anchor⟩" + }, + ["lindenmayer system/axiom"] = { + details = [[ +Sets the axiom (or input string) for the L-system. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/axiom", + meta = "{string}" + }, + ["lindenmayer system/left angle"] = { + details = [[ +This key sets the angle through which the L-system turns when it turns +left. The value is stored in the TeX macro `\pgflsystemrleftangle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/left:angle", + meta = "⟨angle⟩" + }, + ["lindenmayer system/name"] = { + details = [[ +Sets the name for the L-system. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/name", + meta = "{name}" + }, + ["lindenmayer system/order"] = { + details = [[ +Sets the number of iterations the L-system will perform. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/order", + meta = "{integer}" + }, + ["lindenmayer system/randomize angle percent"] = { + details = [[ +If the angles are to be randomized, this key specifies by how much. The +value is stored in the TeX macro `\pgflsystemrandomizeanglepercent`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/randomize:angle:percent", + meta = "⟨percentage⟩" + }, + ["lindenmayer system/randomize step percent"] = { + details = [[ +If the step is to be randomized, this key specifies by how much. The +value is stored in the TeX macro `\pgflsystemrandomizesteppercent`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/randomize:step:percent", + meta = "⟨percentage⟩" + }, + ["lindenmayer system/right angle"] = { + details = [[ +This key sets the angle through which the L-system turns when it turns +right. The value is stored in the TeX macro `\pgflsystemrrightangle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/right:angle", + meta = "⟨angle⟩" + }, + ["lindenmayer system/rule set"] = { + details = [[ +This key allows an (anonymous) L-system to be declared "on-line". There +is, however, a restriction that only the default symbols can be used for +drawing (empty symbols can still be used to control the growth of the +system). The rules in ⟨list⟩ should be separated by commas. + + \tikz[rotate=65]\draw [green!60!black] l-system + [l-system={rule set={F -> F[+F]F[-F]}, axiom=F, order=4, angle=25,step=3pt}]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/rule:set", + meta = "{list}" + }, + ["lindenmayer system/step"] = { + details = [[ +How far the L-system moves forward if required. This key sets the TeX +dimension `\pgflsystemstep`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/step", + meta = "⟨length⟩" + }, + ["local bounding box"] = { + details = [[ +This defines a new node ⟨node name⟩ whose size is the bounding box +around all objects in the current scope starting at the position where +this option was given. After the end of the scope, the ⟨node name⟩ is +still available. You can use this option to keep track of the size of a +certain area. Note that excessive use of this option (keeping track of +dozens of bounding boxes at the same time) will slow things down. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { [local bounding box=outer box] + \draw (1,1) circle (.5) [local bounding box=inner box] (2,2) circle (.5); + } + \draw (outer box.south west) rectangle (outer box.north east); + \draw[red] (inner box.south west) rectangle (inner box.north east); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/local:bounding:box", + meta = "⟨node name⟩" + }, + ["logic gate IEC symbol align"] = { + details = [[ +Set the alignment of the logic gate symbol (in TikZ, when the +`use IEC style logic gates` key has been used, `IEC` can be omitted). +The specification in ⟨align⟩ is a comma separated list from `top`, +`bottom`, `left` or `right`. The distance between the border of the node +and the outer edge of the symbol is determined by the values of the +`inner xsep` and `inner ysep`. + + \begin{tikzpicture}[minimum size=1cm, use IEC style logic gates] + \tikzset{every node/.style={nor gate, draw}} + \node (A) at (0,1.5) {}; + \node [logic gate symbol align={bottom, right}] (B) at (0,0) {}; + \foreach \g in {A, B}{ + \foreach \i in {1,2} + \draw ([xshift=-0.5cm]\g.input \i) -- (\g.input \i); + \draw (\g.output) -- ([xshift=0.5cm]\g.output); + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:IEC:symbol:align", + meta = "⟨align⟩" + }, + ["logic gate IEC symbol color"] = { + details = [[ +This key sets the color for all symbols simultaneously. This color can +be overridden on a case by case basis by specifying a color when setting +the symbol text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:IEC:symbol:color", + meta = "⟨color⟩" + }, + ["logic gate anchors use bounding box"] = { + details = [[ +When set to `true` this key will ensure that the compass point anchors +use the bounding rectangle of the main shape, which, ignore any inverted +inputs or outputs, but includes any `outer sep`. This *only* affects the +compass point anchors and is not set on a shape by shape basis: whether +the bounding box is used is determined by value of this key when the +anchor is accessed. + + \begin{tikzpicture}[minimum height=1.5cm] + \node[xnor gate US, draw, gray!50,line width=2pt] (A) {}; + \foreach \x/\y/\z in {false/blue/1pt, true/red/2pt} + \foreach \a in {north, south, east, west, north east, + south east, north west, south west} + \draw[logic gate anchors use bounding box=\x, color=\y] + (A.\a) circle(\z); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:anchors:use:bounding:box", + meta = "⟨boolean⟩" + }, + ["logic gate input sep"] = { + details = [[ +Set the distance between the *centers* of the inputs to the logic gate. + + \begin{tikzpicture}[minimum size=0.75cm] + \draw [help lines] grid (3,2); + \tikzset{every node/.style={shape=and gate IEC, draw, logic gate inputs=ini}} + \node[logic gate input sep=0.33333cm] at (1,1)(A) {A}; + \node[logic gate input sep=0.5cm] at (3,1) (B) {B}; + \foreach \a in {1,...,3} + \draw (A.input \a -| 0,0) -- (A.input \a) + (B.input \a -| 2,0) -- (B.input \a); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:input:sep", + meta = "⟨length⟩" + }, + ["logic gate inputs"] = { + details = [[ +\[logic-gate-inputs\] Specify the inputs for the logic gate. The keyword +`inverted` indicates an inverted input which will mean PGF will draw a +circle attached to the main shape of the logic gate. Any keyword that is +not `inverted` will be treated as a "normal" or "non-inverted" input +(however, for readability, you may wish to use `normal` or +`non-inverted`), and PGF will not draw the circle. In both cases the +anchors for the inputs will be set up appropriately, numbered from top +to bottom `input 1`, `input 2`, ...and so on. If the gate only supports +one input the anchor is simply called `input` with no numerical index. + + \begin{tikzpicture}[minimum height=0.75cm] + \node[and gate IEC, draw, logic gate inputs={inverted, normal, inverted}] + (A) {}; + \foreach \a in {1,...,3} + \draw (A.input \a -| -1,0) -- (A.input \a); + \draw (A.output) -- ([xshift=0.5cm]A.output); + \end{tikzpicture} + +For multiple inputs it may be somewhat unwieldy to specify a long list, +thus, the following "shorthand" is permitted (this is an extension of +ideas due to Jürgen Werber and Christoph Bartoschek): Using `i` for +inverted and `n` for normal inputs, ⟨input list⟩ can be specified +*without the commas*. So, for example, `ini` is equivalent to +`inverted, normal, inverted`. + + \begin{tikzpicture}[minimum height=0.75cm] + \node[or gate US, draw,logic gate inputs=inini] (A) {}; + \foreach \a in {1,...,5} + \draw (A.input \a -| -1,0) -- (A.input \a); + \draw (A.output) -- ([xshift=0.5cm]A.output); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:inputs", + meta = "⟨input list⟩" + }, + ["logic gate inverted radius"] = { + details = [[ +Set the radius of the circle that is used to indicate inverted inputs. +This is also the radius of the circle used for the inverted output of +the `nand`, `nor`, `xnor` and `not` gates. + + \begin{tikzpicture}[minimum height=0.75cm] + \tikzset{every node/.style={shape=nand gate CDH, draw, logic gate inputs=ii}} + \node[logic gate inverted radius=2pt] {A}; + \node[logic gate inverted radius=4pt] at (0,-1) {B}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:inverted:radius", + meta = "⟨length⟩" + }, + ["magnetic tape tail"] = { + details = [[ +This key sets the thickness of the 'tail' to be ⟨proportion⟩ times the +radius of the shape. The ⟨proportion⟩ should be between `0.0` and `1.0`. + + \begin{tikzpicture}[every node/.style={magnetic tape, draw}] + \node [magnetic tape tail=0.5, magnetic tape tail extend=0.5cm] {A}; + \node [magnetic tape tail=0.25] at (0,1) {B}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/magnetic:tape:tail", + meta = "⟨proportion⟩" + }, + ["magnetic tape tail extend"] = { + details = [[ +This key sets how far the tail extends beyond the radius of the tape. +Negative values will be ignored. + + \begin{tikzpicture}[every node/.style={magnetic tape, draw}] + \node [magnetic tape tail extend=0cm] at (0,0) {A}; + \node [magnetic tape tail extend=0.25cm] at (0,1) {B}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/magnetic:tape:tail:extend", + meta = "⟨distance⟩" + }, + ["magnifying glass handle angle aspect"] = { + details = [[ +The length of the handle as a multiple of the circle radius. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/magnifying:glass:handle:angle:aspect", + meta = "⟨factor⟩" + }, + ["magnifying glass handle angle fill"] = { + details = [[ +The angle of the handle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/magnifying:glass:handle:angle:fill", + meta = "⟨degree⟩" + }, + ["mark color"] = { + details = [[ +Defines the additional fill color for the `halfcircle`, `halfcircle*`, +`halfdiamond*` and `halfsquare*` markers. An empty value uses `white` +(which is the initial configuration). The special value `none` disables +filling of the respective parts. + +Note that `halfsquare` will be filled with `mark color`, and the starred +variant `halfsquare*` will be filled half with `mark color` and half +with the actual `fill` color. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/mark:color", + meta = "{color}" + }, + ["meta-decoration automaton/next state"] = { + details = [[ +After the code for a state has been executed, a state switch to ⟨new +state⟩ is performed. If this option is not given, the next state is the +same as the current state. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/meta-decoration:automaton/next:state", + meta = "⟨new state⟩" + }, + ["meta-decoration automaton/switch if less than"] = { + details = [[ +This causes PGF to check whether the remaining distance to the end of +the input path is less than ⟨dimension⟩, and, if so, to immediately +switch to the state ⟨new state⟩. When this key is evaluated, the macro +`\pgfmetadecoratedpathlength` will be defined as the total length of the +decoration path, allowing for values such as +`\pgfmetadecoratedpathlength/8`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/meta-decoration:automaton/switch:if:less:than", + meta = "⟨dimension⟩ to ⟨new state⟩" + }, + ["meta-decoration automaton/width"] = { + details = [[ +As always, this option will cause an immediate switch to the state +`final` if the remaining distance on the input path is less than +⟨dimension⟩. + +Otherwise, this option tells PGF the width of the "meta-segment", that +is, the length of the sub-input-path which the decoration automaton +specified in ⟨code⟩ will decorate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/meta-decoration:automaton/width", + meta = "⟨dimension⟩" + }, + ["minimum height"] = { + details = [[ +Works like `/pgf/minimum width`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/minimum:height", + meta = "⟨dimension⟩" + }, + ["minimum size"] = { + details = [[ +This style both `/pgf/minimum width` and `/pgf/minimum height` to +⟨dimension⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/minimum:size", + meta = "⟨dimension⟩" + }, + ["minimum width"] = { + details = [[ +This key stores the *recommended* minimum width of a shape. Thus, when a +shape is drawn and when the shape's width would be smaller than +⟨dimension⟩, the shape's width is enlarged by adding some empty space. + +Note that this value is just a recommendation. A shape may choose to +ignore this key. + + \begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfset{minimum width=3cm} + \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/minimum:width", + meta = "⟨dimension⟩" + }, + ["nand gate IEC symbol"] = { + details = [[ +Set the symbol for the `nand gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `nand gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/nand:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["nor gate IEC symbol"] = { + details = [[ +Set the symbol for the `nor gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `nor gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/nor:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["not gate IEC symbol"] = { + details = [[ +Set the symbol for the `not gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `not gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/not:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["number format/1000 sep"] = { + details = [[ +Just another name for `set thousands separator`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/1000:sep", + meta = "{text}" + }, + ["number format/1000 sep in fractionals"] = { + details = [[ +Configures whether the fractional part should also be grouped into +groups of three digits. + +The value `true` will active the `1000 sep` for both, integer and +fractional parts. The value `false` will active `1000 sep` only for the +integer part. + + \pgfkeys{/pgf/number format/.cd, + fixed, + precision=999, + set thousands separator={\,}, + 1000 sep in fractionals, + } + \pgfmathprintnumber{1234.1234567} + + \pgfkeys{/pgf/number format/.cd, + fixed,fixed zerofill, + precision=9, + set thousands separator={\,}, + 1000 sep in fractionals, + } + \pgfmathprintnumber{1234.1234567} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/1000:sep:in:fractionals", + meta = "{boolean}" + }, + ["number format/\\protect\\atmarktext dec sep mark"] = { + details = [[ +Will be placed right before the place where a decimal separator belongs +to. However, `{text}` will be inserted even if there is no decimal +separator. It is intended as place-holder for auxiliary routines to find +alignment positions. + +This key should never be used to change the decimal separator! Use +`dec sep` instead. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/\\protect\\atmarktext:dec:sep:mark", + meta = "{text}" + }, + ["number format/\\protect\\atmarktext sci exponent mark"] = { + details = [[ +Will be placed right before exponents in scientific notation. It is +intended as place-holder for auxiliary routines to find alignment +positions. + +This key should never be used to change the exponent! +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/\\protect\\atmarktext:sci:exponent:mark", + meta = "{text}" + }, + ["number format/assume math mode"] = { + details = [[ +Set this to `true` if you don't want any checks for math mode. The +initial setting checks whether math mode is active using +`\pgfutilensuremath` for each final number. + +Use `assume math mode=true` if you know that math mode is active. In +that case, the final number is typeset as-is, no further checking is +performed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/assume:math:mode", + meta = "{boolean}" + }, + ["number format/dec sep"] = { + details = [[ +Just another name for `set decimal separator`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/dec:sep", + meta = "{text}" + }, + ["number format/every relative"] = { + details = [[ +A style which configures how the `relative` method finally displays its +results. + +The initial configuration is + + \pgfkeys{/pgf/number format/every relative/.style=std} + +Note that rounding is turned off when the resulting style is being +evaluated (since `relative` already rounded the number). + +Although supported, I discourage from using `fixed zerofill` or +`sci zerofill` in this context -- it may lead to a suggestion of higher +precision than is actually used (because `fixed zerofill` might simply +add `.00` although there was a different information before `relative` +rounded the result). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/every:relative" + }, + ["number format/fixed"] = { + details = [[ +Configures `\pgfmathprintnumber` to round the number to a fixed number +of digits after the period, discarding any trailing zeros. + + \pgfkeys{/pgf/number format/.cd,fixed,precision=2} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-04}\hspace{1em} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{24415.98123}\hspace{1em} + \pgfmathprintnumber{123456.12345} + +See section ?? for how to change the appearance. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/fixed" + }, + ["number format/fixed zerofill"] = { + details = [[ +Enables or disables zero filling for any number drawn in fixed point +format. + + \pgfkeys{/pgf/number format/.cd,fixed,fixed zerofill,precision=2} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-04}\hspace{1em} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{24415.98123}\hspace{1em} + \pgfmathprintnumber{123456.12345} + +This key affects numbers drawn with `fixed` or `std` styles (the latter +only if no scientific format is chosen). + + \pgfkeys{/pgf/number format/.cd,std,fixed zerofill,precision=2} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-05}\hspace{1em} + \pgfmathprintnumber{1}\hspace{1em} + \pgfmathprintnumber{123456.12345} + +See section ?? for how to change the appearance. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/fixed:zerofill", + meta = "{boolean}" + }, + ["number format/frac"] = { + details = [[ +Displays numbers as fractionals. + + \pgfkeys{/pgf/number format/frac} + \pgfmathprintnumber{0.333333333333333}\hspace{1em} + \pgfmathprintnumber{0.5}\hspace{1em} + \pgfmathprintnumber{2.133333333333325e-01}\hspace{1em} + \pgfmathprintnumber{0.12}\hspace{1em} + \pgfmathprintnumber{2.666666666666646e-02}\hspace{1em} + \pgfmathprintnumber{-1.333333333333334e-02}\hspace{1em} + \pgfmathprintnumber{7.200000000000000e-01}\hspace{1em} + \pgfmathprintnumber{6.666666666666667e-02}\hspace{1em} + \pgfmathprintnumber{1.333333333333333e-01}\hspace{1em} + \pgfmathprintnumber{-1.333333333333333e-02}\hspace{1em} + \pgfmathprintnumber{3.3333333}\hspace{1em} + \pgfmathprintnumber{1.2345}\hspace{1em} + \pgfmathprintnumber{1}\hspace{1em} + \pgfmathprintnumber{-6} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/frac" + }, + ["number format/frac TeX"] = { + details = [[ +Allows to use a different implementation for `\frac` inside of the +`frac` display type. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/frac:TeX", + meta = "{\\macro}" + }, + ["number format/frac denom"] = { + details = [[ +Allows to provide a custom denominator for `frac`. + + \pgfkeys{/pgf/number format/.cd,frac, frac denom=10} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{0.5}\hspace{1em} + \pgfmathprintnumber{1.2}\hspace{1em} + \pgfmathprintnumber{-0.6}\hspace{1em} + \pgfmathprintnumber{-1.4}\hspace{1em} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/frac:denom", + meta = "⟨int⟩" + }, + ["number format/frac shift"] = { + details = [[ +In case you experience problems because of stability problems, try +experimenting with a different `frac shift`. Higher shift values $k$ +yield higher sensitivity to inaccurate data or inaccurate arithmetics. + +Technically, the following happens. If $r < 1$ is the fractional part of +the mantissa, then a scale $i = 1/r \cdot 10^k$ is computed where $k$ is +the shift; fractional parts of $i$ are neglected. The value $1/r$ is +computed internally, its error is amplified. + +If you still experience stability problems, use `\usepackage{fp}` in +your preamble. The `frac` style will then automatically employ the +higher absolute precision of `fp` for the computation of $1/r$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/frac:shift", + meta = "{integer}" + }, + ["number format/frac whole"] = { + details = [[ +Configures whether complete integer parts shall be placed in front of +the fractional part. In this case, the fractional part will be less then +$1$. Use `frac whole=false` to avoid whole number parts. + + \pgfkeys{/pgf/number format/.cd,frac, frac whole=false} + \pgfmathprintnumber{20.1}\hspace{1em} + \pgfmathprintnumber{5.5}\hspace{1em} + \pgfmathprintnumber{1.2}\hspace{1em} + \pgfmathprintnumber{-5.6}\hspace{1em} + \pgfmathprintnumber{-1.4}\hspace{1em} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/frac:whole", + meta = "⟨true,false⟩" + }, + ["number format/int detect"] = { + details = [[ +Configures `\pgfmathprintnumber` to detect integers automatically. If +the input number is an integer, no period is displayed at all. If not, +the scientific format is chosen. + + \pgfkeys{/pgf/number format/.cd,int detect,precision=2} + \pgfmathprintnumber{15}\hspace{1em} + \pgfmathprintnumber{20}\hspace{1em} + \pgfmathprintnumber{20.4}\hspace{1em} + \pgfmathprintnumber{0.01}\hspace{1em} + \pgfmathprintnumber{0} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/int:detect" + }, + ["number format/int trunc"] = { + details = [[ +Truncates every number to integers (discards any digit after the +period). + + \pgfkeys{/pgf/number format/.cd,int trunc} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-04}\hspace{1em} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{24415.98123}\hspace{1em} + \pgfmathprintnumber{123456.12345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/int:trunc" + }, + ["number format/min exponent for 1000 sep"] = { + details = [[ +Defines the smallest exponent in scientific notation which is required +to draw thousand separators. The exponent is the number of digits minus +one, so $⟨number⟩=4$ will use thousand separators starting with $1e4 = + 10000$. + + \pgfkeys{/pgf/number format/.cd, + int detect, + 1000 sep={\,}, + min exponent for 1000 sep=0} + \pgfmathprintnumber{5000}; \pgfmathprintnumber{1000000} + + \pgfkeys{/pgf/number format/.cd, + int detect, + 1000 sep={\,}, + min exponent for 1000 sep=4} + \pgfmathprintnumber{1000}; \pgfmathprintnumber{5000} + + \pgfkeys{/pgf/number format/.cd, + int detect, + 1000 sep={\,}, + min exponent for 1000 sep=4} + \pgfmathprintnumber{10000}; \pgfmathprintnumber{1000000} + +A value of `0` disables this feature (negative values are ignored). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/min:exponent:for:1000:sep", + meta = "{number}" + }, + ["number format/precision"] = { + details = [[ +Sets the desired rounding precision for any display operation. For +scientific format, this affects the mantissa. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/precision", + meta = "{number}" + }, + ["number format/print sign"] = { + details = [[ +A style which is simply an alias for `showpos=``{boolean}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/print:sign", + meta = "{boolean}" + }, + ["number format/read comma as period"] = { + details = [[ +This is one of the few keys which allows to customize the number parser. +If this switch is turned on, a comma is read just as a period. + + \pgfkeys{/pgf/number format/read comma as period} + \pgfmathprintnumber{1234,56} + +This is typically undesired as it can cause side-effects with math +parsing instructions. However, it is supported to format input numbers +or input tables. Consider `use comma` to typeset the result with a comma +as well. + + \pgfkeys{/pgf/number format/.cd, + read comma as period, + use comma} + \pgfmathprintnumber{1234,56} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/read:comma:as:period", + meta = "⟨true,false⟩" + }, + ["number format/relative style"] = { + details = [[ +The same as `every relative/.append style=``{options}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/relative:style", + meta = "{options}" + }, + ["number format/retain unit mantissa"] = { + details = [[ +Allows to omit a unit mantissa. + + \pgfkeys{ + /pgf/number format/.cd, + sci, retain unit mantissa=false} + \pgfmathprintnumber{10.5}; + \pgfmathprintnumber{10}; + \pgfmathprintnumber{1010}; + \pgfmathprintnumber[precision=1]{-1010}; + +The feature is applied after rounding to the desired precision: if the +remaining mantissa is equal to $1$, it will be omitted. It applies to +all styles involving the scientific format (including `std`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/retain:unit:mantissa", + meta = "⟨true,false⟩" + }, + ["number format/sci"] = { + details = [[ +Configures `\pgfmathprintnumber` to display numbers in scientific +format, that means sign, mantissa and exponent (basis $10$). The +mantissa is rounded to the desired `precision` (or `sci precision`, see +below). + + \pgfkeys{/pgf/number format/.cd,sci,precision=2} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-04}\hspace{1em} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{24415.98123}\hspace{1em} + \pgfmathprintnumber{123456.12345} + +See section ?? for how to change the exponential display style. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci" + }, + ["number format/sci 10\\textasciicircum e"] = { + details = [[ +The same as '`sci 10e`'. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:10\\textasciicircum:e" + }, + ["number format/sci 10e"] = { + details = [[ +Uses $m \cdot 10^e$ for any number displayed in scientific format. + + \pgfkeys{/pgf/number format/.cd,sci,sci 10e} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:10e" + }, + ["number format/sci E"] = { + details = [[ +The same with an uppercase '`E`'. + + \pgfkeys{/pgf/number format/.cd,sci,sci E} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:E" + }, + ["number format/sci e"] = { + details = [[ +Uses the '$1e{+}0$' format which is generated by common scientific tools +for any number displayed in scientific format. + + \pgfkeys{/pgf/number format/.cd,sci,sci e} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:e" + }, + ["number format/sci generic"] = { + details = [[ +Allows to define an own number style for the scientific format. Here, +⟨keys⟩ can be one of the following choices (omit the long key prefix): + + \pgfkeys{ + /pgf/number format/.cd, + sci, + sci generic={mantissa sep=\times,exponent={10^{#1}}}} + \pgfmathprintnumber{12.345}; + \pgfmathprintnumber{0.00012345} + +The ⟨keys⟩ can depend on three parameters, namely on `# 1` which is the +exponent, `# 2` containing the flags entity of the floating point number +and `# 3` is the (unprocessed and unformatted) mantissa. + +Note that `sci generic` is *not* suitable to modify the appearance of +fixed point numbers, nor can it be used to format the mantissa (which is +typeset like fixed point numbers). Use `dec sep`, `1000 sep` and +`print sign` to customize the mantissa. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:generic", + meta = "{keys}" + }, + ["number format/sci generic/exponent"] = { + details = [[ +Provides text to format the exponent. The actual exponent is available +as argument `# 1` (see below). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:generic/exponent", + meta = "{text}" + }, + ["number format/sci generic/mantissa sep"] = { + details = [[ +Provides the separator between a mantissa and the exponent. It might be +`\cdot`, for example, +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:generic/mantissa:sep", + meta = "{text}" + }, + ["number format/sci precision"] = { + details = [[ +Sets the desired rounding precision only for `sci` styles. + +Use `sci precision={}` to restore the initial configuration (which uses +the argument provided to `precision` for all number styles). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:precision", + meta = "⟨number or empty⟩" + }, + ["number format/sci subscript"] = { + details = [[ +Typesets the exponent as subscript for any number displayed in +scientific format. This style requires very little space. + + \pgfkeys{/pgf/number format/.cd,sci,sci subscript} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:subscript" + }, + ["number format/sci superscript"] = { + details = [[ +Typesets the exponent as superscript for any number displayed in +scientific format. This style requires very little space. + + \pgfkeys{/pgf/number format/.cd,sci,sci superscript} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:superscript" + }, + ["number format/sci zerofill"] = { + details = [[ +Enables or disables zero filling for any number drawn in scientific +format. + + \pgfkeys{/pgf/number format/.cd,sci,sci zerofill,precision=2} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-04}\hspace{1em} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{24415.98123}\hspace{1em} + \pgfmathprintnumber{123456.12345} + +As with `fixed zerofill`, this option does only affect numbers drawn in +`sci` format (or `std` if the scientific format is chosen). + +See section ?? for how to change the exponential display style. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:zerofill", + meta = "{boolean}" + }, + ["number format/set decimal separator"] = { + details = [[ +Assigns `{text}` as decimal separator for any fixed point numbers +(including the mantissa in sci format). + +Use `\pgfkeysgetvalue{/pgf/number format/set decimal separator}\value` +to get the current separator into `\value`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/set:decimal:separator", + meta = "{text}" + }, + ["number format/set thousands separator"] = { + details = [[ +Assigns `{text}` as thousands separator for any fixed point numbers +(including the mantissa in sci format). + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={}} + \pgfmathprintnumber{1234.56} + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={}} + \pgfmathprintnumber{1234567890} + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={.}} + \pgfmathprintnumber{1234567890} + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={,}} + \pgfmathprintnumber{1234567890} + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={{{,}}}} + \pgfmathprintnumber{1234567890} + +The last example employs commas and disables the default comma-spacing. + +Use `\pgfkeysgetvalue{/pgf/number format/set thousands separator}\value` +to get the current separator into `\value`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/set:thousands:separator", + meta = "{text}" + }, + ["number format/showpos"] = { + details = [[ +Enables or disables the display of plus signs for non-negative numbers. + + \pgfkeys{/pgf/number format/showpos} + \pgfmathprintnumber{12.345} + + \pgfkeys{/pgf/number format/showpos=false} + \pgfmathprintnumber{12.345} + + \pgfkeys{/pgf/number format/.cd,showpos,sci} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/showpos", + meta = "{boolean}" + }, + ["number format/skip 0."] = { + details = [[ +Configures whether numbers like $0.1$ shall be typeset as $.1$ or not. + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill,precision=2, + skip 0.} + \pgfmathprintnumber{0.56} + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill,precision=2, + skip 0.=false} + \pgfmathprintnumber{0.56} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/skip:0.", + meta = "{boolean}" + }, + ["number format/use comma"] = { + details = [[ +A predefined style which installs commas "`,`" as decimal separators and +periods "`.`" as thousands separators. + + \pgfkeys{/pgf/number format/.cd,fixed,precision=2,use comma} + \pgfmathprintnumber{12.3456} + + \pgfkeys{/pgf/number format/.cd,fixed,precision=2,use comma} + \pgfmathprintnumber{1234.56} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/use:comma" + }, + ["number format/use period"] = { + details = [[ +A predefined style which installs periods "`.`" as decimal separators +and commas "`,`" as thousands separators. This style is the default. + + \pgfkeys{/pgf/number format/.cd,fixed,precision=2,use period} + \pgfmathprintnumber{12.3456} + + \pgfkeys{/pgf/number format/.cd,fixed,precision=2,use period} + \pgfmathprintnumber{1234.56} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/use:period" + }, + ["number format/verbatim"] = { + details = [[ +A style which configures the number printer to produce verbatim text +output, i.e., it doesn't contain TeX macros. + + \pgfkeys{ + /pgf/fpu, + /pgf/number format/.cd, + sci, + verbatim} + \pgfmathprintnumber{12.345}; + \pgfmathprintnumber{0.00012345}; + \pgfmathparse{exp(15)} + \pgfmathprintnumber{\pgfmathresult} + +The style resets `1000 sep`, `dec sep`, `print sign`, `skip 0.` and sets +`assume math mode`. Furthermore, it installs a `sci generic` format for +verbatim output of scientific numbers. + +However, it will still respect `precision`, `fixed zerofill`, +`sci zerofill` and the overall styles `fixed`, `sci`, `int detect` (and +their variants). It might be useful if you intend to write output files. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/verbatim" + }, + ["number format/zerofill"] = { + details = [[ +Sets both `fixed zerofill` and `sci zerofill` at once. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/zerofill", + meta = "{boolean}" + }, + ["or gate IEC symbol"] = { + details = [[ +Set the symbol for the `or gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `or gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/or:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["outer sep"] = { + details = [[ +This option adds an additional (invisible) separation space of +⟨dimension⟩ outside the background path. The main effect of this option +is that all anchors will move a little "to the outside". + +For those familiar with CSS, this is same as *margin*. + +The default for this option is half the line width. When the default is +used and when the background path is draw, the anchors will lie exactly +on the "outside border" of the path (not on the path itself). + + \begin{tikzpicture} + \draw[line width=5pt] + (0,0) node[fill=yellow!80!black] (f) {filled} + (2,0) node[draw] (d) {drawn} + (1,-2) node[draw,scale=2] (s) {scaled}; + + \draw[->] (1,-1) -- (f); + \draw[->] (1,-1) -- (d); + \draw[->] (1,-1) -- (s); + \end{tikzpicture} + +As the above example demonstrates, the standard settings for the outer +sep are not always "correct". First, when a shape is filled, but not +drawn, the outer sep should actually be `0`. Second, when a node is +scaled, for instance by a factor of 5, the outer separation also gets +scaled by a factor of 5, while the line width stays at its original +width; again causing problems. + +In such cases, you can say `outer sep=auto` to make TikZ *try* to +compensate for the effects described above. This is done by, firstly, +setting the outer sep to `0` when no drawing is done and, secondly, +setting the outer separations to half the line width (as before) times +two adjustment factors, one for the horizontal separations and one for +the vertical separations (see Section ?? for details on these factors). +Note, however, that these factors can compensate only for +transformations that are either scalings plus rotations or scalings with +different magnitudes in the horizontal and the vertical direction. If +you apply slanting, the factors will only approximate the correct +values. + +In general, it is a good idea to say `outer sep=auto` at some early +stage. It is not the default mainly for compatibility with earlier +versions. + + \begin{tikzpicture}[outer sep=auto] + \draw[line width=5pt] + (0,0) node[fill=yellow!80!black] (f) {filled} + (2,0) node[draw] (d) {drawn} + (1,-2) node[draw,scale=2] (s) {scaled}; + + \draw[->] (1,-1) -- (f); + \draw[->] (1,-1) -- (d); + \draw[->] (1,-1) -- (s); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/outer:sep", + meta = "⟨dimension or ``auto''⟩" + }, + ["outer xsep"] = { + details = [[ +This key stores the recommended horizontal separation between the +background path and the "outer anchors". For example, if ⟨dimension⟩ is +`1cm` then the `east` anchor will be 1cm to the right of the right +border of the background path. As before, this value is just a +recommendation. + + \begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfset{outer xsep=.5cm} + \pgfnode{rectangle}{center}{Hello World}{x}{\pgfusepath{stroke}} + + \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/outer:xsep", + meta = "⟨dimension⟩" + }, + ["outer ysep"] = { + details = [[ +Works like `/pgf/outer xsep`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/outer:ysep", + meta = "⟨dimension⟩" + }, + ["pattern keys/angle"] = { + details = [[ +By default the stars are arranged on a regular grid. The whole pattern +is rotated by this angle. The rotation angle is measured in the +mathematically positive sense. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/angle" + }, + ["pattern keys/distance"] = { + details = [[ +Distance between stars. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/distance" + }, + ["pattern keys/line width"] = { + details = [[ +Thickness of the lines. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/line:width" + }, + ["pattern keys/points"] = { + details = [[ +Number of pointy ends of the stars. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/points" + }, + ["pattern keys/radius"] = { + details = [[ +Outer radius of the enclosing circle of the stars. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/radius" + }, + ["pattern keys/xshift"] = { + details = [[ +Shifts the whole pattern in $x$-direction (before applying the +rotation). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/xshift" + }, + ["pattern keys/yshift"] = { + details = [[ +Shifts the whole pattern in $y$-direction (before applying the +rotation). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/yshift" + }, + ["patterns/bottom left"] = { + details = [[ +Bottom left corner of the pattern's bounding box, +e.g. `\pgfqpoint{-.1pt}{-.1pt}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/bottom:left", + meta = "⟨pgfpoint⟩" + }, + ["patterns/code"] = { + details = [[ +The code should be PGF code that can be protocolled. It should not +contain any color code or nodes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/code", + meta = "⟨code⟩" + }, + ["patterns/defaults"] = { + details = [[ +This list holds default assignments to the parameters passed to the +pattern. The default keys can then be found under the +`/pgf/pattern keys/` prefix. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/defaults", + meta = "⟨comma separated list⟩" + }, + ["patterns/name"] = { + details = [[ +The name of the pattern by which it can be used later on. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/name", + meta = "⟨name⟩" + }, + ["patterns/parameters"] = { + details = [[ +A list of parameters that are passed to the pattern. This is usually a +list of TeX macros. It is very important that these macros are fully +expandable because the values they hold are being used for deduplication +in the PDF file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/parameters", + meta = "⟨comma separated list⟩" + }, + ["patterns/set up code"] = { + details = [[ +This code can be set if parameters have to be preprocessed before the +actual pattern code can be run. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/set:up:code", + meta = "⟨code⟩" + }, + ["patterns/tile size"] = { + details = [[ +Width and height of a single of the pattern as a PGF point +specification, i.e. the $x$ coordinate is the width and the $y$ +specification, i.e. the $x$ coordinate is the width and the $y$ +coordinate is the height, e.g. `\pgfqpoint{3pt}{3pt}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/tile:size", + meta = "⟨pgfpoint⟩" + }, + ["patterns/tile transformation"] = { + details = [[ +A PGF transformation, e.g. `\pgftransformrotate{30}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/tile:transformation", + meta = "⟨pgftransformation⟩" + }, + ["patterns/top right"] = { + details = [[ +Top right corner of the pattern's bounding box, +e.g. `\pgfqpoint{3.1pt}{3.1pt}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/top:right", + meta = "⟨pgfpoint⟩" + }, + ["patterns/type"] = { + details = [[ +The type of the pattern maps to what was called "form only" and +"inherently colored" in the language of the normal patterns. The +available choices are: + +- `uncolored` the pattern will obey the surrounding color. + +- `colored` the pattern will have an intrinsic color. + +- `form only` synonym for `uncolored` + +- `inherently colored` synonym for `colored` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/type", + meta = "⟨type⟩" + }, + ["patterns/x"] = { + details = [[ +Unit vector of the coordinate system in the $x$-direction. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/x", + meta = "⟨dimension⟩" + }, + ["patterns/y"] = { + details = [[ +Unit vector of the coordinate system in the $y$-direction. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/y", + meta = "⟨dimension⟩" + }, + ["plot/gnuplot call"] = { + details = [[ +This key can be used to change the way gnuplot is called. + +Some portable MiKTeX distribution needs something like the following. + + \pgfkeys{/pgf/plot/gnuplot call="/Programs/gnuplot/binary/gnuplot"} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/plot/gnuplot:call", + meta = "⟨gnuplot invocation⟩" + }, + ["random starburst"] = { + details = [[ +Sets the seed for the random number generator for creating the +starburst. The maximum value for ⟨integer⟩ is `16383`. If ⟨integer⟩`=0`, +the random number generator will not be used, and the maximum point +height will be used for all outer points. If ⟨integer⟩ is omitted, a +seed will be randomly chosen. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/random:starburst", + meta = "⟨integer⟩" + }, + ["rectangle split allocate boxes"] = { + details = [[ +This key checks if ⟨number⟩ boxes have been allocated, and if not, it +allocates the required boxes using `\newbox` (some "magic" is performed +to get around the fact that `\newbox` is declared `\outer` in plain +TeX). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:allocate:boxes", + meta = "⟨number⟩" + }, + ["rectangle split draw splits"] = { + details = [[ +Sets whether the line or lines between node parts will be drawn. +Internally, this sets the TeX-if `\ifpgfrectanglesplitdrawsplits` +appropriately. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:draw:splits", + meta = "⟨boolean⟩" + }, + ["rectangle split empty part depth"] = { + details = [[ +Sets the default depth for a node part box if it is empty and empty +parts are not ignored. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:empty:part:depth", + meta = "⟨length⟩" + }, + ["rectangle split empty part height"] = { + details = [[ +Sets the default height for a node part box if it is empty and empty +parts are not ignored. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:empty:part:height", + meta = "⟨length⟩" + }, + ["rectangle split empty part width"] = { + details = [[ +Sets the default width for a node part box if it is empty and empty +parts are not ignored. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:empty:part:width", + meta = "⟨length⟩" + }, + ["rectangle split horizontal"] = { + details = [[ +This key determines whether the rectangle is split horizontally or +vertically +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:horizontal", + meta = "⟨boolean⟩" + }, + ["rectangle split ignore empty parts"] = { + details = [[ +When ⟨boolean⟩ is true, PGF will ignore any part that is empty *except +the text part*. This effectively overrides the `rectangle split parts` +key in that, if 3 parts (for example) are specified, but one is empty, +only two will be shown. + + \begin{tikzpicture}[every node/.style={draw, anchor=text, rectangle split, + rectangle split parts=3}] + \node {text \nodepart{second} \nodepart{third}third}; + \node [rectangle split ignore empty parts] at (2,0) + {text \nodepart{second} \nodepart{third}third}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:ignore:empty:parts", + meta = "⟨boolean⟩" + }, + ["rectangle split part align"] = { + details = [[ +Sets the alignment of the boxes inside the node parts. Each item in +⟨list⟩ should be separated by commas (so if there is more than one item +in ⟨list⟩, it must be surrounded by braces). + +When the rectangle is split vertically, the entries in ⟨list⟩ must be +one of `left`, `right`, or `center`. If ⟨list⟩ has less entries than +node parts then the remaining boxes are aligned according to the last +entry in the list. Note that this only aligns the boxes in each part and +*does not* affect the alignment of the contents of the boxes. + + \def\x{one \nodepart{two} 2 \nodepart{three} three \nodepart{four} 4} + \begin{tikzpicture}[ + every node/.style={rectangle split, rectangle split parts=4, + draw} + ] + \node[rectangle split part align={center, left, right}] at (0,0) {\x}; + \node[rectangle split part align={center, left}] at (1.25,0) {\x}; + \node[rectangle split part align={center}] at (2.5,0) {\x}; + \end{tikzpicture} + +When the rectangle is split horizontally, the entries in ⟨list⟩ must be +one of `top`, `bottom`, `center` or `base`. Note that using the value +`base` will only make sense if all the node part boxes are being aligned +in this way. This is because the `base` value aligns the boxes in +relation to each other, whereas the other values align the boxes in +relation to the part of the shape they occupy. + + \def\x{\Large w\nodepart{two}x\nodepart{three}\Huge y\nodepart{four}\tiny z} + \begin{tikzpicture}[ + every node/.style={rectangle split, rectangle split parts=4, + draw, rectangle split horizontal} + ] + \node[rectangle split part align={center, top, bottom}] at (0,0) {\x}; + \node[rectangle split part align={center, top}] at (0,-1.25) {\x}; + \node[rectangle split part align={center}] at (0,-2.5) {\x}; + \node[rectangle split part align=base] at (0,-3.75) {\x}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:part:align", + meta = "{⟨list⟩}" + }, + ["rectangle split part fill"] = { + details = [[ +Sets the custom fill color for each node part shape. The items in ⟨list⟩ +should be separated by commas (so if there is more than one item in +⟨list⟩, it must be surrounded by braces). If ⟨list⟩ has less entries +than node parts, then the remaining node parts use the color from the +last entry in the list. This key will automatically set +`/pgf/rectangle split use custom fill`. + + \begin{tikzpicture} + \tikzset{every node/.style={rectangle split, draw, minimum width=.5cm}} + \node[rectangle split part fill={red!50, green!50, blue!50, yellow!50}] {}; + \node[rectangle split part fill={red!50, green!50, blue!50}] at (0.75,0) {}; + \node[rectangle split part fill={red!50, green!50}] at (1.5,0) {}; + \node[rectangle split part fill={red!50}] at (2.25,0) {}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:part:fill", + meta = "{⟨list⟩}" + }, + ["rectangle split parts"] = { + details = [[ +Split the rectangle into ⟨number⟩ parts, which should be in the range +`1` to `20`. If more than four parts are needed, the boxes should be +allocated in advance as described above. + + \begin{tikzpicture}[every text node part/.style={align=center}] + \node[rectangle split, rectangle split parts=3, draw, text width=2.75cm] + {Student + \nodepart{two} + age:int \\ + name:String + \nodepart{three} + getAge():int \\ + getName():String}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:parts", + meta = "⟨number⟩" + }, + ["rectangle split use custom fill"] = { + details = [[ +This enables the use of a custom fill for each of the node parts +(including the area covered by the `inner sep`). The background path for +the shape should not be filled (e.g., in TikZ, the `fill` option for the +node must be implicity or explicitly set to `none`). Internally, this +key sets the TeX-if `\ifpgfrectanglesplitusecustomfill` appropriately. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:use:custom:fill", + meta = "⟨boolean⟩" + }, + ["regular polygon sides"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/regular:polygon:sides", + meta = "⟨integer⟩" + }, + ["rounded rectangle arc length"] = { + details = [[ +Sets the length of the arcs for the rounded ends. Recommended values for +⟨angle⟩ are between `90` and `180`. + + \begin{tikzpicture} + \matrix[row sep=5pt, every node/.style={draw, rounded rectangle}]{ + \node[rounded rectangle arc length=180] {180}; \\ + \node[rounded rectangle arc length=120] {120}; \\ + \node[rounded rectangle arc length=90] {90}; \\}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rounded:rectangle:arc:length", + meta = "⟨angle⟩" + }, + ["rounded rectangle east arc"] = { + details = [[ +Sets the style of the rounding for the east side. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rounded:rectangle:east:arc", + meta = "⟨arc type⟩" + }, + ["rounded rectangle left arc"] = { + details = [[ +Alternative key for specifying the west arc. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rounded:rectangle:left:arc", + meta = "⟨arc type⟩" + }, + ["rounded rectangle right arc"] = { + details = [[ +Alternative key for specifying the east arc. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rounded:rectangle:right:arc", + meta = "⟨arc type⟩" + }, + ["rounded rectangle west arc"] = { + details = [[ +Sets the style of the rounding for the left side. The permitted values +for ⟨arc type⟩ are `concave`, `convex`, or `none`. + + \begin{tikzpicture} + \matrix[row sep=5pt, every node/.style={draw, rounded rectangle}]{ + \node[rounded rectangle west arc=concave] {Concave}; \\ + \node[rounded rectangle west arc=convex] {Convex}; \\ + \node[rounded rectangle left arc=none] {None}; \\}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rounded:rectangle:west:arc", + meta = "⟨arc type⟩" + }, + ["shape aspect"] = { + details = [[ +Sets a desired aspect ratio for the shape. For the `diamond` shape, this +option sets the ratio between width and height of the shape. + + \begin{tikzpicture} + \draw (0,0) node[shape aspect=1,diamond,draw] {aspect 1}; + \draw (0,-2) node[shape aspect=2,diamond,draw] {aspect 2}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/shape:aspect", + meta = "⟨aspect ratio⟩" + }, + ["shape border rotate"] = { + details = [[ +Rotates the border of a shape independently of the node contents, but in +addition to any other transformations. If the shape border is not +constructed using the incircle, the rotation will be rounded to the +nearest integer multiple of 90 degrees when the shape is drawn. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/shape:border:rotate", + meta = "⟨angle⟩" + }, + ["shape border uses incircle"] = { + details = [[ +Determines if the border of a shape is constructed using the incircle. +If no value is given ⟨boolean⟩ will take the default value `true`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/shape:border:uses:incircle", + meta = "⟨boolean⟩" + }, + ["signal from"] = { + details = [[ +Sets which sides take an inward pointer (i.e., that points towards the +center of the shape). The possible values for ⟨direction⟩ and ⟨opposite +direction⟩ are the compass point directions `north`, `south`, `east` and +`west` (or `above`, `below`, `right` and `left`). An additional keyword +`nowhere` can be used to reset the sides so they have no pointers. When +used with `signal from` key, this only resets inward pointers; used with +the `signal to` key, it only resets outward pointers. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/signal:from", + meta = "⟨direction⟩ and ⟨opposite direction⟩" + }, + ["signal pointer angle"] = { + details = [[ +Sets the angle for the pointed sides of the shape. This angle is +maintained when enforcing any minimum size requirements, so any +adjustment to the width will affect the height, and vice versa. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/signal:pointer:angle", + meta = "⟨angle⟩" + }, + ["signal to"] = { + details = [[ +Sets which sides take an outward pointer (i.e., that points away from +the shape). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/signal:to", + meta = "⟨direction⟩ and ⟨opposite direction⟩" + }, + ["single arrow head extend"] = { + details = [[ +This sets the distance between the tail of the arrow and the outer end +of the arrow head. This may change if the shape is enlarged to some +minimum width. + + \begin{tikzpicture} + \node[single arrow, draw, single arrow head extend=.5cm, gray!50, rotate=60] + (a) {Arrow}; + \draw[red, |<->|] (a.before tip) -- (a.before head) + node [midway, below, sloped, black] {head extend}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/single:arrow:head:extend", + meta = "⟨length⟩" + }, + ["single arrow head indent"] = { + details = [[ +This moves the point where the arrow head joins the shaft of the arrow +*towards* the arrow tip, by ⟨length⟩. + + \begin{tikzpicture}[every node/.style={single arrow, draw=none, rotate=60}] + \node [fill=red!50] {arrow 1}; + \node [fill=blue!50, single arrow head indent=1ex] at (1.5,0) {arrow 2}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/single:arrow:head:indent", + meta = "⟨length⟩" + }, + ["single arrow tip angle"] = { + details = [[ +Sets the angle for the arrow tip. Enlarging the arrow to some minimum +width may increase the height of the shape to maintain this angle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/single:arrow:tip:angle", + meta = "⟨angle⟩" + }, + ["star point height"] = { + details = [[ +Sets the height of the star points. This is the distance between the +inner point and outer point radii. If the star is enlarged to some +specified minimum size, the inner radius is increased to maintain the +point height. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/star:point:height", + meta = "⟨distance⟩" + }, + ["star point ratio"] = { + details = [[ +Sets the ratio between the inner point and outer point radii. If the +star is enlarged to some specified minimum size, the inner radius is +increased to maintain the ratio. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/star:point:ratio", + meta = "⟨number⟩" + }, + ["star points"] = { + details = [[ +Sets the number of points for the star. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/star:points", + meta = "⟨integer⟩" + }, + ["starburst point height"] = { + details = [[ +Sets the *maximum* distance between the inner point radius and the outer +point radius. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/starburst:point:height", + meta = "⟨length⟩" + }, + ["starburst points"] = { + details = [[ +Sets the number of outer points for the starburst. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/starburst:points", + meta = "⟨integer⟩" + }, + step = { + details = [[ +Sets the horizontal stepping to the $x$-coordinate of ⟨vector⟩ and the +vertical stepping to its $y$-coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/step", + meta = "⟨vector⟩" + }, + stepx = { + details = [[ +The horizontal stepping. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/stepx", + meta = "⟨dimension⟩" + }, + stepy = { + details = [[ +The vertical stepping. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/stepy", + meta = "⟨dimension⟩" + }, + ["tape bend bottom"] = { + details = [[ +Specifies how the bottom side bends. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tape:bend:bottom", + meta = "⟨bend style⟩" + }, + ["tape bend height"] = { + details = [[ +Sets the total height for a side with a bend. + + \begin{tikzpicture}[>=stealth] + \draw [help lines] grid(3,2); + \node [tape, fill, minimum size=2cm, red!50, tape bend top=none, + tape bend height=1cm] at (1.5,1.5) (t) {}; + \draw [|<->|, blue] (1.5,0) -- (1.5,1) + node [at end, above, black]{tape bend height}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tape:bend:height", + meta = "⟨length⟩" + }, + ["tape bend top"] = { + details = [[ +Specifies how the top side bends. The ⟨bend style⟩ is either +`in and out`, `out and in` or `none` (i.e., a straight line). The +bending sides are drawn in a clockwise direction, and using the bend +style `in and out` will mean the side will first bend inwards and then +bend outwards. The opposite holds true for `out and in`. + + \begin{tikzpicture}[-stealth] + \node[tape, draw, gray, minimum width=2cm](t){Tape}; + \draw [blue]([yshift=5pt] t.north west) -- ([yshift=5pt]t.north east) + node[midway, above, black]{in and out}; + \draw [blue]([yshift=-5pt]t.south east) -- ([yshift=-5pt]t.south west) + node[sloped, allow upside down, midway, above, black]{in and out}; + \end{tikzpicture} + +This might take a bit of getting used to, but just remember that when +you want the bendy sides to be parallel, the sides take the same bend +style. It is possible for the top and bottom sides to take opposite bend +styles, but the author of this shape cannot think of a single use for +such a combination. + + \begin{tikzpicture}[every node/.style={tape, draw}] + \node [tape bend top=out and in, tape bend bottom=out and in] {Parallel}; + \node at (2,0) [tape bend bottom=out and in] {Why?}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tape:bend:top", + meta = "⟨bend style⟩" + }, + ["tex4ht node/class"] = { + details = [[ +This option allows you to give a class name to the node, allowing it to +be styled by a CSS file (only with `tex4ht node/escape=true`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tex4ht:node/class", + meta = "⟨class name⟩" + }, + ["tex4ht node/css"] = { + details = [[ +This option allows you to tell the browser what CSS file it should use +to style the display of the node (only with `tex4ht node/escape=true`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tex4ht:node/css", + meta = "⟨filename⟩" + }, + ["tex4ht node/escape"] = { + details = [[ +Selects the rendering method for a text node with the tex4ht driver. + +When this key is set to `false`, text is translated into SVG text, which +is somewhat limited: simple characters (letters, numerals, punctuation, +$\sum$, $\int$, ...), subscripts and superscripts (but not +subsubscripts) will display but everything else will be filtered out, +ignored or will produce invalid HTML code (in the worst case). This +means that two kind of texts render reasonably well: + +1. First, plain text without math mode, special characters or anything + else special. + +2. Second, *very* simple mathematical text that contains subscripts or + superscripts. Even then, variables are not correctly set in italics + and, in general, text simple does not look very nice. + +If you use text that contains anything special, even something as simple +as `\textbackslash alpha`, this may corrupt the graphic. + + \tikz \node[draw,/pgf/tex4ht node/escape=false] {Example : $(a+b)^2=a^2+2ab+b^2$}; + +When you write `node[/pgf/tex4ht node/escape=true] {`⟨text⟩`}`, +PGF escapes back to HTML to render the ⟨text⟩. This method produces +valid HTML code in most cases and the support for complicated text nodes +is much better since code that renders well outside a `{pgfpicture}`, +should also render well inside a text node. Another advantage is that +inside text nodes with fixed width, HTML will produce line breaks for +long lines. On the other hand, you need a browser with good SVG support +to display the picture. Also, the text will display differently, +depending on your browsers, the fonts you have on your system and your +settings. Finally, PGF has to guess the size of the text rendered by the +browser to scale it and prevent it from sticking from the node. When it +fails, the text will be either cropped or too small. + + \tikz \node[draw,/pgf/tex4ht node/escape=true] + {Example : $\int_0^\infty\frac{1}{1+t^2}dt=\frac{\pi}{2}$}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tex4ht:node/escape", + meta = "⟨boolean⟩" + }, + ["tex4ht node/id"] = { + details = [[ +This option allows you to give a unique id to the node, allowing it to +be styled by a CSS file (only with `tex4ht node/escape=true`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tex4ht:node/id", + meta = "⟨id name⟩" + }, + ["text mark"] = { + details = [[ +Changes the text shown by `mark=text`. + +With `/pgf/text mark=m`: + +With `/pgf/text mark=A`: + +There is no limitation about the number of characters or whatever. In +fact, any TeX material can be inserted as `{text}`, including images. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text:mark", + meta = "{text}" + }, + ["text mark as node"] = { + details = [[ +Configures how `mark=text` will be drawn: either as `\node` or as +`\pgftext`. + +The first choice is highly flexible and possibly slow, the second is +very fast and usually enough. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text:mark:as:node", + meta = "{boolean}" + }, + ["text mark style"] = { + details = [[ +Defines a set of options which control the appearance of `mark=text`. + +If `/pgf/text mark as node=false` (the default), `{options}` is provided +as argument to `\pgftext` -- which provides only some basic keys like +`left`, `right`, `top`, `bottom`, `base` and `rotate`. + +If `/pgf/text mark as node=true`, `{options}` is provided as argument to +`\node`. This means you can provide a very powerful set of options +including `anchor`, `scale`, `fill`, `draw`, `rounded corners` etc. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text:mark:style", + meta = "{options for mark=text}" + }, + ["text/at"] = { + details = [[ +Translates the origin (that is, the point where the text is shown) to +⟨point⟩. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,at={\pgfpoint{1cm}{0cm}}] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/at", + meta = "⟨point⟩" + }, + ["text/base"] = { + details = [[ +This key causes the text box to be placed such that its baseline is on +the origin. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base] {lovely}} + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,right] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/base" + }, + ["text/bottom"] = { + details = [[ +This key causes the text box to be placed such that its bottom is on the +origin. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[bottom] {lovely}} + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[bottom,right] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/bottom" + }, + ["text/left"] = { + details = [[ +The key causes the text box to be placed such that its left border is on +the origin. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[left] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/left" + }, + ["text/right"] = { + details = [[ +The key causes the text box to be placed such that its right border is +on the origin. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[right] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/right" + }, + ["text/rotate"] = { + details = [[ +Rotates the coordinate system by ⟨degree⟩. This will also rotate the +text box. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,x=1cm,y=-0.5cm,rotate=30] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/rotate", + meta = "⟨degree⟩" + }, + ["text/top"] = { + details = [[ +This key causes the text box to be placed such that its top is on the +origin. This option can be used together with the `left` or `right` +option. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[top] {lovely}} + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[top,right] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/top" + }, + ["text/x"] = { + details = [[ +Translates the origin by ⟨dimension⟩ along the $x$-axis. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,x=1cm,y=-0.5cm] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/x", + meta = "⟨dimension⟩" + }, + ["text/y"] = { + details = [[ +This key works like the `x` option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/y", + meta = "⟨dimension⟩" + }, + tips = { + details = [[ +This key governs in what situations arrow tips are added to a path. The +following ⟨values⟩ are permissible: + +- `true` (the value used when no ⟨value⟩ is specified) + +- `proper` + +- `on draw` (the initial value, if the key has not yet been used at + all) + +- `on proper draw` + +- `never` or `false` (same effect) + +Firstly, there are a whole bunch of situations where the setting of +these (or other) options causes no arrow tips to be shown: + +- If no arrow tips have been specified (for instance, by having said + `arrows=-`), no arrow tips are drawn. + +- If the `clip` option is set, no arrow tips are drawn. + +- If `tips` has been set to `never` or `false`, no arrow tips are + drawn. + +- If `tips` has been set to `on draw` or `on proper draw`, but the + `draw` option is not set, no arrow tips are drawn. + +- If the path is empty (as in `\path ;`), no arrow tips are drawn. + +- If at least one of the subpaths of a path is closed (`cycle` is used + somewhere or something like `circle` or `rectangle`), arrow tips are + never drawn anywhere -- even if there are open subpaths. + +Now, if we pass all of the above tests, we must have a closer look at +the path. All its subpaths must now be open and there must be at least +one subpath. We consider the last one. Arrow tips will only be added to +this last subpath. + +1. If this last subpath not degenerate (all coordinates on the subpath + are the same as in a single "move-to" `\path (0,0);` or in a + "move-to" followed by a "line-to" to the same position as in + `\path (1,2) – (1,2)`), arrow tips are added to this last subpath + now. + +2. If the last subpath is degenerate, we add arrow tips pointing upward + at the single coordinate mentioned in the path, but only for `tips` + begin set to `true` or to `on draw` -- and not for `proper` nor for + `on proper draw`. In other words, "proper" suppresses arrow tips on + degenerate paths. + + + + % No path, no arrow tips: + \tikz [<->] \draw; + + % Degenerate path, draw arrow tips (but no path, it is degenerate...) + \tikz [<->] \draw (0,0); + + % Degenerate path, tips=proper suppresses arrows + \tikz [<->] \draw [tips=proper] (0,0); + + % Normal case: + \tikz [<->] \draw (0,0) -- (1,0); + + % Two subpaths, only second gets tips + \tikz [<->] \draw (0,0) -- (1,0) (2,0) -- (3,0); + + % Two subpaths, second degenerate, but still gets tips + \tikz [<->] \draw (0,0) -- (1,0) (2,0); + + % Two subpaths, second degenerate, proper suppresses them + \tikz [<->] \draw [tips=on proper draw] (0,0) -- (1,0) (2,0); + + % Two subpaths, but one is closed: No tips, even though last subpath is open + \tikz [<->] \draw (0,0) circle[radius=2pt] (2,0) -- (3,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tips", + meta = "⟨value⟩" + }, + ["trapezium angle"] = { + details = [[ +This key stores no value itself, but sets the value of the previous two +keys to ⟨angle⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trapezium:angle", + meta = "⟨angle⟩" + }, + ["trapezium left angle"] = { + details = [[ +Sets the lower internal angle of the left side. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trapezium:left:angle", + meta = "⟨angle⟩" + }, + ["trapezium right angle"] = { + details = [[ +Sets the lower internal angle of the right side. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trapezium:right:angle", + meta = "⟨angle⟩" + }, + ["trapezium stretches"] = { + details = [[ +This key controls whether PGF allows the width and the height of the +trapezium to be enlarged independently, when considering any minimum +size specification. This is initially `false`, ensuring that the shape +"looks the same but bigger" when enlarged. + + \tikzset{my node/.style={trapezium, fill=#1!20, draw=#1!75, text=black}} + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \node [my node=red] {A}; + \node [my node=green, minimum height=1.5cm] at (1, 1.25) {B}; + \node [my node=blue, minimum width=1.5cm] at (2, 0) {C}; + \end{tikzpicture} + +By setting ⟨boolean⟩ to `true`, the trapezium can be stretched +horizontally or vertically. + + \tikzset{my node/.style={trapezium, fill=#1!20, draw=#1!75, text=black}} + \begin{tikzpicture} + \tikzset{trapezium stretches=true} + \draw [help lines] grid (3,2); + \node [my node=red] {A}; + \node [my node=green, minimum height=1.5cm] at (1, 1.25) {B}; + \node [my node=blue, minimum width=1.5cm] at (2, 0) {C}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trapezium:stretches", + meta = "⟨boolean⟩" + }, + ["trapezium stretches body"] = { + details = [[ +This is similar to the `trapezium stretches` key except that when +⟨boolean⟩ is `true`, PGF enlarges only the body of the trapezium when +applying minimum width. + + \tikzset{my node/.style={trapezium, fill=#1!20, draw=#1!75, text=black}} + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \node [my node=red] at (1.5,.25) {A}; + \node [my node=green, minimum width=3cm, trapezium stretches] + at (1.5,1) {B}; + \node [my node=blue, minimum width=3cm, trapezium stretches body] + at (1.5,1.75) {C}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trapezium:stretches:body", + meta = "⟨boolean⟩" + }, + ["trig format"] = { + details = [[ +Allows to define whether trigonometric math functions (i.e. all in this +subsection) operate with degrees or with radians. + + \pgfmathparse{cos(45)} \pgfmathresult + + \pgfkeys{/pgf/trig format=rad} + \pgfmathparse{cos(pi/2)} \pgfmathresult + +The initial configuration `trig format=deg` is the base of PGF: almost +all of it is based on degrees. + +Specifying `trig format=rad` is most useful for data visualization where +the angles are typically given in radians. However, it is applied to all +trigonometric functions for which the option applies, including any +drawing instructions which operate on angles. + + \begin{tikzpicture} + \draw[-stealth] + (0:1) -- (45:1) -- (90:1) -- (135:1) -- (180:1); + + \draw[-stealth,trig format=rad,red] + (pi:1) -- (5/4*pi:1) -- (6/4*pi:1) -- (7/4*pi:1) -- (2*pi:1); + \end{tikzpicture} + +#### Warning: + +At the time of this writing, this feature is "experimental". Please +handle it with care: there may be path instructions or libraries in +PGF which rely on `trig format=deg`. The intended usage of +`trig format=rad` is for local scopes -- and as option for data +visualization. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trig:format", + meta = "⟨deg,rad⟩" + }, + ["trim lowlevel"] = { + details = [[ +This affects only the basic level image externalization: the initial +configuration `trim lowlevel=false` stores the normal image, without +trimming, and the trimming into a separate file. This allows reduced +bounding boxes without clipping the rest away. The `trim lowlevel=true` +information causes the image externalization to store the trimmed image, +possibly resulting in clipping. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trim:lowlevel", + meta = "⟨true,false⟩" + }, + ["xnor gate IEC symbol"] = { + details = [[ +Set the symbol for the `xnor gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `xnor gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/xnor:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["xor gate IEC symbol"] = { + details = [[ +Set the symbol for the `xor gate`. Note the necessity for braces, as the +symbol contains `=`. In TikZ, when the `use IEC style logic gates` key +has been used, this key can be replaced by `xor gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/xor:gate:IEC:symbol", + meta = "⟨text⟩" + } + } +} |