diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex')
| -rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex | 1298 |
1 files changed, 648 insertions, 650 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex index 15926efe567..b26efb1b87c 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex @@ -11,64 +11,61 @@ \section{Defining New Arrow Tip Kinds} \label{section-arrows} - \subsection{Overview} -In present section we have a look at how you can define new arrow tips -for use in \pgfname. The low-level commands for selecting which arrow -tips are to be used have already been described in -Section~\ref{section-tips}, the general syntax rules for using arrows -are detailed in Section~\ref{section-tikz-arrows}. Although -Section~\ref{section-tikz-arrows} describes the use of arrows in -\tikzname, in reality, \tikzname\ itself does not actually do anything -about arrow tips; all of the functionality is implemented on the -\pgfname\ level in the commands described in -Section~\ref{section-tikz-arrows}. Indeed, even the |/.tip| key -handler described in Section~\ref{section-tikz-arrows} is actually -implemented on the \pgfname\ layer. - -What has \emph{not} yet been covered is how you can actually define a -complete new arrow tip. In \pgfname, arrows are ``meta-arrows'' in the -same way that fonts in \TeX\ are ``meta-fonts.'' When a meta-arrow is -resized, it is not simply scaled, but a possibly complicated -transformation is applied to the size. - -A meta-font is not one particular font at a specific size with a -specific stroke width (and with a large number of other parameters -being fixed). Rather, it is a ``blueprint'' (actually, more like a -program) for generating such a font at a particular size and -width. This allows the designer of a meta-font to make sure that, say, -the font is somewhat thicker and wider at very small sizes. To -appreciate the difference: Compare the following texts: ``Berlin'' and -``\tikz{\node [scale=2,inner sep=0pt,outer sep=0pt]{\tiny - Berlin};}''. The first is a ``normal'' text, the second is the tiny -version scaled by a factor of two. Obviously, the first look -better. Now, compare ``\tikz{\node [scale=.5,inner sep=0pt,outer - sep=0pt]{Berlin};}'' and ``{\tiny Berlin}''. This time, the normal -text was scaled down, while the second text is a ``normal'' tiny -text. The second text is easier to read. - -\pgfname's meta-arrows work in a similar fashion: The shape of an -arrow tip can vary according to a great number of parameters, the line -width of the arrow tip being one of them. Thus, an arrow tip drawn at -a line width of 5pt will typically \emph{not} be five times as large -as an arrow tip of line width 1pt. Instead, the size of the arrow will -get bigger only slowly as the line width increases. +In present section we have a look at how you can define new arrow tips for use +in \pgfname. The low-level commands for selecting which arrow tips are to be +used have already been described in Section~\ref{section-tips}, the general +syntax rules for using arrows are detailed in +Section~\ref{section-tikz-arrows}. Although Section~\ref{section-tikz-arrows} +describes the use of arrows in \tikzname, in reality, \tikzname\ itself does +not actually do anything about arrow tips; all of the functionality is +implemented on the \pgfname\ level in the commands described in +Section~\ref{section-tikz-arrows}. Indeed, even the |/.tip| key handler +described in Section~\ref{section-tikz-arrows} is actually implemented on the +\pgfname\ layer. + +What has \emph{not} yet been covered is how you can actually define a complete +new arrow tip. In \pgfname, arrows are ``meta-arrows'' in the same way that +fonts in \TeX\ are ``meta-fonts''. When a meta-arrow is resized, it is not +simply scaled, but a possibly complicated transformation is applied to the +size. + +A meta-font is not one particular font at a specific size with a specific +stroke width (and with a large number of other parameters being fixed). Rather, +it is a ``blueprint'' (actually, more like a program) for generating such a +font at a particular size and width. This allows the designer of a meta-font to +make sure that, say, the font is somewhat thicker and wider at very small +sizes. To appreciate the difference: Compare the following texts: ``Berlin'' +and ``\tikz{\node [scale=2,inner sep=0pt,outer sep=0pt]{\tiny Berlin};}''. The +first is a ``normal'' text, the second is the tiny version scaled by a factor +of two. Obviously, the first look better. Now, compare ``\tikz{\node +[scale=.5,inner sep=0pt,outer sep=0pt]{Berlin};}'' and ``{\tiny Berlin}''. This +time, the normal text was scaled down, while the second text is a ``normal'' +tiny text. The second text is easier to read. + +\pgfname's meta-arrows work in a similar fashion: The shape of an arrow tip can +vary according to a great number of parameters, the line width of the arrow tip +being one of them. Thus, an arrow tip drawn at a line width of 5pt will +typically \emph{not} be five times as large as an arrow tip of line width 1pt. +Instead, the size of the arrow will get bigger only slowly as the line width +increases. To appreciate the difference, here are the |Latex| and -|Classical TikZ Rightarrow| arrows, as drawn by \pgfname\ at four different sizes: +|Classical TikZ Rightarrow| arrows, as drawn by \pgfname\ at four different +sizes: \medskip \begin{tikzpicture}[1/.tip=Latex, 2/.tip=Classical TikZ Rightarrow] - \draw[-1, line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; - \draw[-1, line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; - \draw[-1, line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; - \draw[-1, line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; - - \draw[-2, line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; - \draw[-2, line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; - \draw[-2, line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; - \draw[-2, line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; + \draw[-1, line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; + \draw[-1, line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; + \draw[-1, line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; + \draw[-1, line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; + + \draw[-2, line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; + \draw[-2, line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; + \draw[-2, line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; + \draw[-2, line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; \end{tikzpicture} \medskip @@ -88,434 +85,431 @@ Here, by comparison, are the same arrows when they are simply ``resized'': \end{tikzpicture} \bigskip -As can be seen, simple scaling produces arrow tips that are way too -large at larger sizes and way too small at smaller sizes. +As can be seen, simple scaling produces arrow tips that are way too large at +larger sizes and way too small at smaller sizes. -In addition to the line width, other options may also influence the -appearance of an arrow tip. In particular, the width of the inner line -(the line used to create the effect of a double line) influences arrow -tips as well as other options that are specific to the arrow tip. +In addition to the line width, other options may also influence the appearance +of an arrow tip. In particular, the width of the inner line (the line used to +create the effect of a double line) influences arrow tips as well as other +options that are specific to the arrow tip. \subsection{Terminology} \label{section-arrow-terminology} -Before we have a look at the exact commands used for defining arrow -tips, we need to fix some terminology. Consider the following drawing -of an arrow tip where the arrow tip is drawn transparently so that we -can see what is ``happening behind it'': - +Before we have a look at the exact commands used for defining arrow tips, we +need to fix some terminology. Consider the following drawing of an arrow tip +where the arrow tip is drawn transparently so that we can see what is +``happening behind it'': +% \begin{tikzpicture} - \draw [red!50, ,line width=1cm] (0,0) -- (4,0); - \path [tips, opacity=.25,line width=1cm, -{Stealth[black,line width=0pt,length=4cm, width=4cm, inset=1cm]}] (0,0) -- (6,0); - - \draw [->,thick] (1,0) -- (8,0) node [right] {$x$-axis}; - \draw [->,thick] (5,-2.25) -- (5,2.25) node [above] {$y$-axis}; - - \foreach \i in {-3,-2,-1,1,2} \draw (\i+5,-1mm) -- (\i+5,1mm) node [above] {\small$\i$}; - \foreach \i in {-2,-1,1,2} \draw (49mm,\i) -- (51mm,\i) node [right] {\small$\i$};; + \draw [red!50, ,line width=1cm] (0,0) -- (4,0); + \path [tips, opacity=.25,line width=1cm, -{Stealth[black,line width=0pt,length=4cm, width=4cm, inset=1cm]}] (0,0) -- (6,0); + + \draw [->,thick] (1,0) -- (8,0) node [right] {$x$-axis}; + \draw [->,thick] (5,-2.25) -- (5,2.25) node [above] {$y$-axis}; + + \foreach \i in {-3,-2,-1,1,2} \draw (\i+5,-1mm) -- (\i+5,1mm) node [above] {\small$\i$}; + \foreach \i in {-2,-1,1,2} \draw (49mm,\i) -- (51mm,\i) node [right] {\small$\i$};; \end{tikzpicture} -I have also added a coordinate system. The code for drawing an arrow -tip always draws it in the way shown above: Pointing right along the -$x$-axis. +I have also added a coordinate system. The code for drawing an arrow tip always +draws it in the way shown above: Pointing right along the $x$-axis. We will use the following terminology: +% \begin{itemize} -\item The point where tip of the arrow ends is called the - \emph{tip end}. It is at $(1,0)$ in our example and we always - assume it to lie on the $x$-axis, so we just treat it as a distance, - 1 in this case. This is the position where the original path was - supposed to end (so if the arrow tip had not been added to the red - path, it would have ended here). -\item The \emph{back end} of the arrow is where a vertical line just - to the left of the arrow intersects the $x$-axis. In our case, this - is the point $(-3,0)$ and again we treat it as a distance, $-3$ in - this case. -\item The \emph{line end} is the position where the path now - ends. This should be a position inside the arrow head that gets - ``covered'' by the path. Note that a path may have a round or a rect - head and should still be covered. Clearly, necessary shortening of - the path will be the difference between the tip end and the line - end. -\item The \emph{visual back end} is the position where the path and - the the arrow head ``meet last'' on the path. In our case, because - of the inset, the visual back end is not the same as the back end: - The arrow ends ``visually'' at $(-2,0)$. The difference between the - back end and the visual back end is important when the arrow tip is - flexed, see Section~\ref{section-arrow-flex} for an explanation of - flexing. -\item There is also a \emph{visual tip end}, the counterpart of the - visual back end for the front. In our case, the visual tip end and - the tip end obviously coincide, but if we were to reverse the arrow - tip, the visual tip end would be different form the tip end (while - the visual back end would then coincide with the new back end). -\item There are four points that make up the \emph{convex hull} of the - arrow tip: $(1,0)$, $(-3,2)$, and $(-3,-2)$. - - Normally, \pgfname\ automatically keeps track of a bounding box of - everything you draw. However, since arrow tips are drawn so often, - \pgfname\ caches the code needing for drawing arrow tips internally - and because of this cache it cannot determine the size of the arrow - tip just based on the drawing commands used for drawing the - tip. Instead, a convex hull of the arrow tip must be explicitly - provided in the definition. + \item The point where tip of the arrow ends is called the \emph{tip end}. + It is at $(1,0)$ in our example and we always assume it to lie on the + $x$-axis, so we just treat it as a distance, 1 in this case. This is + the position where the original path was supposed to end (so if the + arrow tip had not been added to the red path, it would have ended + here). + \item The \emph{back end} of the arrow is where a vertical line just to the + left of the arrow intersects the $x$-axis. In our case, this is the + point $(-3,0)$ and again we treat it as a distance, $-3$ in this case. + \item The \emph{line end} is the position where the path now ends. This + should be a position inside the arrow head that gets ``covered'' by the + path. Note that a path may have a round or a rect head and should still + be covered. Clearly, necessary shortening of the path will be the + difference between the tip end and the line end. + \item The \emph{visual back end} is the position where the path and the the + arrow head ``meet last'' on the path. In our case, because of the + inset, the visual back end is not the same as the back end: The arrow + ends ``visually'' at $(-2,0)$. The difference between the back end and + the visual back end is important when the arrow tip is flexed, see + Section~\ref{section-arrow-flex} for an explanation of flexing. + \item There is also a \emph{visual tip end}, the counterpart of the visual + back end for the front. In our case, the visual tip end and the tip end + obviously coincide, but if we were to reverse the arrow tip, the visual + tip end would be different form the tip end (while the visual back end + would then coincide with the new back end). + \item There are four points that make up the \emph{convex hull} of the + arrow tip: $(1,0)$, $(-3,2)$, and $(-3,-2)$. + + Normally, \pgfname\ automatically keeps track of a bounding box of + everything you draw. However, since arrow tips are drawn so often, + \pgfname\ caches the code needing for drawing arrow tips internally and + because of this cache it cannot determine the size of the arrow tip + just based on the drawing commands used for drawing the tip. Instead, a + convex hull of the arrow tip must be explicitly provided in the + definition. \end{itemize} -When you design a new arrow tip, all of the above parameters must be -defined. +When you design a new arrow tip, all of the above parameters must be defined. -\subsection{Caching and Rendering of Arrows} -As a last preparation for the description of the commands for -declaring arrows, it is important to understand the exact process by -which \pgfname\ draws arrows. +\subsection{Caching and Rendering of Arrows} +As a last preparation for the description of the commands for declaring arrows, +it is important to understand the exact process by which \pgfname\ draws +arrows. +% \begin{enumerate} -\item First, you have to define an arrow tip kind using - |\pgfdeclarearrow{name=foo,...|. This will tell \pgfname\ that %} - |foo| is now the name of an arrow tip. In particular, the - parser for arrow tip specifications will now treat |foo| as the name - of an arrow tip and will not try to consider |f|, |o|, and |o| as - the names of single-char shorthands. - - Other than storing the definitions in the declaration internally, - this command has little other effect. In particular, no drawing or - other processing takes place. -\item Now assume that at some point the arrow tip |foo| is actually - used. In this case, certain options may have been set, for instance - the user may have requested the arrow tip - |foo[length=5pt,open]|. What happens next depends on whether it is - the first time the arrow tip |foo| is used with \emph{these exact - options} ornot. -\item Assume that is the first time |foo| is requested at a length of - 5pt and in an ``open'' version. \pgfname\ now retrieves the - definition of the arrow tip kind that it stored in the first step - and executes the so-called \emph{setup} code. When this code is - executed, all the options will be in force (for - instance, |\pgfarrowlength| will equal |5pt| in our case). The job - of the setup code is two-fold: First, it needs to compute all of the - parameters listed in Section~\ref{section-arrow-terminology}, that - is, it has to compute where the tip end will lie in the arrow tip's - coordinate system \emph{at the particular size of 5pt}, where the - back end will be, where the convex hull points lie, and so - on. Second, the setup code should precompute values that will be - important for constructing the path of the arrow. In our example, - there is little to do in this regard, but for more complicated - arrows, all time-consuming preparations are done now. - - It is \emph{not} the job of the setup to actually draw the arrow - tip, only to ``prepare'' this as much as possible. - - The setup code will always be executed only once for each arrow tip - kind for a given set of options. Thus, when a user uses - |foo[length=5pt,open]| once more later anywhere in the document, the - setup code will not be executed again. -\item The next thing that happens is that we have a look at the - \emph{drawin code} stored in the |code| field of the arrow. In our - example, the drawing code would consist of creating a filled path - with four straight segments. - - In most cases, what happens now is that the drawing code is executed in a - special sandbox in which the low-level driver commands that do the - actual drawing are intercepted and stored away in a so-called - \emph{cache}. Once such a cache has been created, its contents will - be reused whenever |foo[length=5pt,open]| is requested by a user and - just like the setup code, the drawing code will not be executed - again. - - There are, however, two cases in which the drawing code gets executed - each time the arrow is used: First, an arrow tip kind can specify - that this should always happen by saying |cachable=false| in its - definition. This is necessary if the drawing code contains - low-level drawing commands that cannot be intercepted such as a use - of |\pgftext| for arrow tips that ``contain text.'' Second, when the - |bend| option is used, the same arrow tip will look different each - time it is used, namely in dependence on the exact curvature of the - path to which it is added. - - Because the drawing code may be executed several times, while the - setup code may not, we must find a way to ``communicate'' the - values computed by the setup code to the drawing code. This is done - by explicitly calling |\pgfarrowssave| inside the setup - code. Whatever is ``saved'' in this way is restored each time before - the drawing code is executed. + \item First, you have to define an arrow tip kind using + |\pgfdeclarearrow{name=foo,...|. This will tell \pgfname\ that |foo| is %} + now the name of an arrow tip. In particular, the parser for arrow tip + specifications will now treat |foo| as the name of an arrow tip and + will not try to consider |f|, |o|, and |o| as the names of single-char + shorthands. + + Other than storing the definitions in the declaration internally, this + command has little other effect. In particular, no drawing or other + processing takes place. + \item Now assume that at some point the arrow tip |foo| is actually used. + In this case, certain options may have been set, for instance the user + may have requested the arrow tip |foo[length=5pt,open]|. What happens + next depends on whether it is the first time the arrow tip |foo| is + used with \emph{these exact options} or not. + \item Assume that is the first time |foo| is requested at a length of 5pt + and in an ``open'' version. \pgfname\ now retrieves the definition of + the arrow tip kind that it stored in the first step and executes the + so-called \emph{setup} code. When this code is executed, all the + options will be in force (for instance, |\pgfarrowlength| will equal + |5pt| in our case). The job of the setup code is two-fold: First, it + needs to compute all of the parameters listed in + Section~\ref{section-arrow-terminology}, that is, it has to compute + where the tip end will lie in the arrow tip's coordinate system + \emph{at the particular size of 5pt}, where the back end will be, where + the convex hull points lie, and so on. Second, the setup code should + precompute values that will be important for constructing the path of + the arrow. In our example, there is little to do in this regard, but + for more complicated arrows, all time-consuming preparations are done + now. + + It is \emph{not} the job of the setup to actually draw the arrow tip, + only to ``prepare'' this as much as possible. + + The setup code will always be executed only once for each arrow tip + kind for a given set of options. Thus, when a user uses + |foo[length=5pt,open]| once more later anywhere in the document, the + setup code will not be executed again. + \item The next thing that happens is that we have a look at the + \emph{drawin code} stored in the |code| field of the arrow. In our + example, the drawing code would consist of creating a filled path with + four straight segments. + + In most cases, what happens now is that the drawing code is executed in + a special sandbox in which the low-level driver commands that do the + actual drawing are intercepted and stored away in a so-called + \emph{cache}. Once such a cache has been created, its contents will be + reused whenever |foo[length=5pt,open]| is requested by a user and just + like the setup code, the drawing code will not be executed again. + + There are, however, two cases in which the drawing code gets executed + each time the arrow is used: First, an arrow tip kind can specify that + this should always happen by saying |cachable=false| in its definition. + This is necessary if the drawing code contains low-level drawing + commands that cannot be intercepted such as a use of |\pgftext| for + arrow tips that ``contain text''. Second, when the |bend| option is + used, the same arrow tip will look different each time it is used, + namely in dependence on the exact curvature of the path to which it is + added. + + Because the drawing code may be executed several times, while the setup + code may not, we must find a way to ``communicate'' the values computed + by the setup code to the drawing code. This is done by explicitly + calling |\pgfarrowssave| inside the setup code. Whatever is ``saved'' + in this way is restored each time before the drawing code is executed. \end{enumerate} -As can be seen, the process is a bit involved, but it leads to -a reasonably fast arrow tip management. +As can be seen, the process is a bit involved, but it leads to a reasonably +fast arrow tip management. \subsection{Declaring an Arrow Tip Kind} \begin{command}{\pgfdeclarearrow\marg{config}} - 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. - - \medskip - \noindent\textbf{Defining a Complete New Arrow Tip Kind.} - The \meta{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: - - \begin{itemize} - \item \declare{|name|}|=|\meta{name} or |name=|\meta{start name}|-|\meta{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 fist 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. - \item \declare{|parameters|}|=|\marg{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~\ref{section-arrow-options}.) - - 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 \meta{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 \meta{list of macros} should be set to - |\the\pgfarrowlength,\the\pgfarrowwidth|. (Actually, the comma is - optional, the \meta{list of macros} does not really have to be a - list, just something that can be expanded unambiuously.) - - 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 \pgfname\ thinks that it can reuse some - code when, in reality, this code actually depends on a parameter - not listed here. - - \item \declare{|setup code|}|=|\marg{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 \meta{code} gets executed (only this - once). The code can now do aribtrarily complicated computations - the prepare the later drawing of the arrow tip. Also the - \meta{code} must specify the different tip and back ends and the - convex hull points. This is done by calling the following macros - inside the \meta{code}: - - \begin{command}{\pgfarrowssettipend\marg{dimension}} - 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 \meta{dimension}. For example, for our earlier - example of the large arrow tip, where the tip end was at 1cm, we - would call + 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. + + + \medskip + \noindent\textbf{Defining a Complete New Arrow Tip Kind.} + The \meta{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: + % + \begin{itemize} + \item \declare{|name|}|=|\meta{name} or |name=|\meta{start + name}|-|\meta{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 fist 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. + \item \declare{|parameters|}|=|\marg{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~\ref{section-arrow-options}.) + + 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 \meta{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 \meta{list of macros} should be set to + |\the\pgfarrowlength,\the\pgfarrowwidth|. (Actually, the comma is + optional, the \meta{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 \pgfname\ thinks that it can reuse some code + when, in reality, this code actually depends on a parameter not + listed here. + \item \declare{|setup code|}|=|\marg{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 \meta{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 \meta{code} must + specify the different tip and back ends and the convex hull points. + This is done by calling the following macros inside the + \meta{code}: + % + \begin{command}{\pgfarrowssettipend\marg{dimension}} + 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 \meta{dimension}. For example, for our earlier + example of the large arrow tip, where the tip end was at 1cm, + we would call + % \begin{codeexample}[code only] -\pgfarrowssettipend{1cm} +\pgfarrowssettipend{1cm} \end{codeexample} - Note that for efficience reasons, the \meta{dimension} is not - passed through |\pgfmathsetlength|; rather what happens is that - |\pgf@x=|\meta{dimension} gets executed. In particular, you can - pack further computations into the \meta{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: + % + Note that for efficiency reasons, the \meta{dimension} is not + passed through |\pgfmathsetlength|; rather what happens is that + |\pgf@x=|\meta{dimension} gets executed. In particular, you can + pack further computations into the \meta{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: + % \begin{codeexample}[code only] -\pgfarrowssettipend{1cm\advance\pgf@x by-.5\pgflinewidth} +\pgfarrowssettipend{1cm\advance\pgf@x by-.5\pgflinewidth} \end{codeexample} - If the command is not called at all inside the setup code, the - tip end is set to |0pt|. - \end{command} - - \begin{command}{\pgfarrowssetbackend\marg{dimension}} - Works like the command for the tip end, only it sets the back - end. In our example we would call + % + If the command is not called at all inside the setup code, the + tip end is set to |0pt|. + \end{command} + + \begin{command}{\pgfarrowssetbackend\marg{dimension}} + Works like the command for the tip end, only it sets the back + end. In our example we would call + % \begin{codeexample}[code only] -\pgfarrowssettipend{-3cm} +\pgfarrowssettipend{-3cm} \end{codeexample} - Defaults to |0pt|. - \end{command} - - \begin{command}{\pgfarrowssetlineend\marg{dimension}} - Sets the line end, so in the example we have - |\pgfarrowssettipend{-1cm}|. Default to |0pt|. - \end{command} - - \begin{command}{\pgfarrowssetvisualbackend\marg{dimension}} - Sets the visual back end, |\pgfarrowssetvisualbackend{-2cm}| in - our example. Default to the value of the normal back end. - \end{command} - - \begin{command}{\pgfarrowssetvisualtipend\marg{dimension}} - Sets the visual tip end. Default to the value of the normal tip - end and, thus, we need not set it in our example. - \end{command} - - \begin{command}{\pgfarrowshullpoint\marg{x dimension}\marg{y dimension}} - Adds a point to the convex hull of the arrow tip. As for the - previous commands, no math parsing is done; instead \pgfname\ - says |\pgf@x=|\meta{x dimension} and then |\pgf@y=|\meta{y - dimension}. Thus, both ``dimensions'' can contain code for - advancing and thus modifying |\pgf@x| and |\pgf@y|. - - In our example we would write + % + Defaults to |0pt|. + \end{command} + + \begin{command}{\pgfarrowssetlineend\marg{dimension}} + Sets the line end, so in the example we have + |\pgfarrowssettipend{-1cm}|. Default to |0pt|. + \end{command} + + \begin{command}{\pgfarrowssetvisualbackend\marg{dimension}} + Sets the visual back end, |\pgfarrowssetvisualbackend{-2cm}| in + our example. Default to the value of the normal back end. + \end{command} + + \begin{command}{\pgfarrowssetvisualtipend\marg{dimension}} + Sets the visual tip end. Default to the value of the normal tip + end and, thus, we need not set it in our example. + \end{command} + + \begin{command}{\pgfarrowshullpoint\marg{x dimension}\marg{y dimension}} + Adds a point to the convex hull of the arrow tip. As for the + previous commands, no math parsing is done; instead \pgfname\ + says |\pgf@x=|\meta{x dimension} and then |\pgf@y=|\meta{y + dimension}. Thus, both ``dimensions'' can contain code for + advancing and thus modifying |\pgf@x| and |\pgf@y|. + + In our example we would write + % \begin{codeexample}[code only] \pgfarrowshullpoint{1cm}{0pt} \pgfarrowshullpoint{-3cm}{2cm} \pgfarrowshullpoint{-3cm}{-2cm} \end{codeexample} - \end{command} + \end{command} + \begin{command}{\pgfarrowsupperhullpoint\marg{x dimension}\marg{y dimension}} + This command works like the previous command, only it normally + adds \emph{two} points to the convex hull: First, the point + $(\meta{x dimension},\meta{y dimension})$ and, secondly, the + point $(\meta{x dimension},-\meta{y dimension})$. However, the + second point is only added if the arrow is not a harpoon. - \begin{command}{\pgfarrowsupperhullpoint\marg{x dimension}\marg{y dimension}} - This command works like the previous command, only it normally - adds \emph{two} points to the convex hull: First, the point $(\meta{x - dimension},\meta{y dimension})$ and, secondly, the point $(\meta{x - dimension},-\meta{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 + Thus, in our example we could simplify the convex hull to + % \begin{codeexample}[code only] \pgfarrowshullpoint{1cm}{0pt} \pgfarrowsupperhullpoint{-3cm}{2cm} \end{codeexample} - If the \meta{y dimension} is zero or less, only one point, - namely $(\meta{x dimension},\meta{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. - \end{command} - - \begin{command}{\pgfarrowssave\marg{macro}} - 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. - \end{command} - - \begin{command}{\pgfarrowssavethe\marg{register}} - Works like |\pgfarrowssave|, only the parameter must be a - register and |\the|\meta{register} will be saved. - Typically, you will write something like + % + If the \meta{y dimension} is zero or less, only one point, + namely $(\meta{x dimension},\meta{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. + \end{command} + + \begin{command}{\pgfarrowssave\marg{macro}} + 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. + \end{command} + + \begin{command}{\pgfarrowssavethe\marg{register}} + Works like |\pgfarrowssave|, only the parameter must be a + register and |\the|\meta{register} will be saved. Typically, + you will write something like + % \begin{codeexample}[code only] \pgfarrowssavethe{\pgfarrowlength} \pgfarrowssavethe{\pgfarrowwidth} \end{codeexample} - To ensure that inside the drawing code the the dimension - registers |\pgfarrowlength| and |\pgfarrowwidth| are setup with - the values they had during the setup. - \end{command} - - \item \declare{|drawing code|}|=|\marg{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 \meta{code} will we stored - in a special cache; but in some cases the \meta{code} gets - executed each time the arrow tip is used, so do not assume - anything about it. Inside the \meta{code}, you have access to all - values that were saved in the setup code as well as to the line - width. - - The \meta{code} should draw the arrow tip ``going right along the - $x$-axis.'' \pgfname\ 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 \meta{code}: - \begin{itemize} - \item - In the \meta{code} you may \emph{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. - \item - 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. - \item - When the arrow tip code is executed, it is automatically put - inside a low-level scope, so nothing will ``leak out'' from the - scope. - \item - The high-level coordinate transformation matrix will be set to the - identity matrix when the code is executed for the first time. + % + To ensure that inside the drawing code the the dimension + registers |\pgfarrowlength| and |\pgfarrowwidth| are setup with + the values they had during the setup. + \end{command} + \item \declare{|drawing code|}|=|\marg{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 \meta{code} will we stored in a special cache; but in + some cases the \meta{code} gets executed each time the arrow tip is + used, so do not assume anything about it. Inside the \meta{code}, + you have access to all values that were saved in the setup code as + well as to the line width. + + The \meta{code} should draw the arrow tip ``going right along the + $x$-axis''. \pgfname\ 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 \meta{code}: + % + \begin{itemize} + \item In the \meta{code} you may \emph{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. + \item 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. + \item When the arrow tip code is executed, it is automatically + put inside a low-level scope, so nothing will ``leak out'' + from the scope. + \item The high-level coordinate transformation matrix will be + set to the identity matrix when the code is executed for + the first time. + \end{itemize} + \item \declare{|cache|}|=|\meta{true or false} + + When set to |true|, which is the default, the \meta{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~\ref{section-protocols}) 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|. + \item \declare{|bending mode|}|=|\meta{mode} + + This key is important only when the |bend| option is used with an + arrow, see Section~\ref{section-arrow-flex} 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 + \meta{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~\ref{section-library-curvilinear} for details. Which of + these ways is use can be configured by setting \meta{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|. + \item \declare{|defaults|}|=|\meta{arrow keys} + + The \meta{arrow keys} allow you to configure the default values for + the parameters on which an arrow tip depends. The \meta{arrow keys} + will be executed first before any other arrow tip options are + executed, see Section~\ref{section-arrow-scopes} for the exact + sequence. Also see Section~\ref{section-arrow-options} below for + more details on arrow options. \end{itemize} - - \item \declare{|cache|}|=|\meta{true or false} - - When set to |true|, which is the default, the \meta{code} will be - executed only once for a partiular value of parameters and the - low-level commands created by the drawing code (using the system - layer protocol subsystem, see Section~\ref{section-protocols}) - 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|. - - \item \declare{|bending mode|}|=|\meta{mode} - - This key is important only when the |bend| option is used with an - arrow, see Section~\ref{section-arrow-flex} 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 - \meta{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~\ref{section-library-curvilinear} for details. Which of - these ways is use can be configured by setting \meta{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|. - - \item \declare{|defaults|}|=|\meta{arrow keys} - - The \meta{arrow keys} allow you to configure the default values - for the parameters on which an arrow tip depends. The \meta{arrow - keys} will be executed first before any other arrow tip options - are executed, see Section~\ref{section-arrow-scopes} for the exact - sequence. Also see Section~\ref{section-arrow-options} below for - more details on arrow options. - \end{itemize} - - 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 examlpe. 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: + + 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: + % \begin{codeexample}[code only] \pgfdeclarearrow{ name = foo, @@ -534,17 +528,19 @@ a reasonably fast arrow tip management. \pgfarrowssavethe\pgfarrowlength }, drawing code = { - \pgfpathmoveto{.25\pgfarrowlength}{0pt} - \pgfpathlineto{-.75\pgfarrowlength}{.5\pgfarrowlength} - \pgfpathlineto{-.5\pgfarrowlength}{0pt} - \pgfpathlineto{-.75\pgfarrowlength}{-.5\pgfarrowlength} + \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 } -} +} \end{codeexample} - We can now use it: + % + We can now use it: + % \pgfdeclarearrow{ name = foo, parameters = { \the\pgfarrowlength }, @@ -570,306 +566,305 @@ a reasonably fast arrow tip management. \pgfusepathqfill }, defaults = { length = 4cm } -} +} \begin{codeexample}[] -\tikz \draw [-foo] (0,0) -- (8,0); +\tikz \draw [-foo] (0,0) -- (8,0); \end{codeexample} \begin{codeexample}[] -\tikz \draw [-{foo[length=2cm,bend]}] (0,0) to [bend left] (3,0); +\tikz \draw [-{foo[length=2cm,bend]}] (0,0) to [bend left] (3,0); \end{codeexample} - \medskip - \noindent\textbf{Defining a Shorthand.} - The |\pgfdeclarearrow| command can also used to define - \emph{shorthands}. This works as follows: - \begin{itemize} - \item First, you must provide a |name| just in the same way as when - you define a full-flung new arrow tip kind. - \item Second, instead of all of the other options listed above, you - just use one more option: - - \smallskip - \declare{|means|}|=|\meta{end arrow specification} - - This sets up things so that whenever \meta{name} is now used in an - arrow specification, it will be replaced by the \meta{end arrow - specification} (the problems resulting form the \meta{name} - begin used in a start arrow specification are taken care of - automatically). See also Section~\ref{section-arrow-tip-macro} for - details on the order in which options get executed in such cases. - - Note that the \meta{end arrow specification} will be executed - immediately to build the so-called arrow option caches, a concept - explored in more detail in - Section~\ref{section-arrow-option-cache}. 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 - \meta{end arrow specification} will be evaluated immediately. For - instance, when you write + + \medskip + \noindent\textbf{Defining a Shorthand.} + The |\pgfdeclarearrow| command can also used to define + \emph{shorthands}. This works as follows: + \begin{itemize} + \item First, you must provide a |name| just in the same way as when you + define a full-flung new arrow tip kind. + \item Second, instead of all of the other options listed above, you + just use one more option: + + \smallskip + \declare{|means|}|=|\meta{end arrow specification} + + This sets up things so that whenever \meta{name} is now used in an + arrow specification, it will be replaced by the \meta{end arrow + specification} (the problems resulting form the \meta{name} begin + used in a start arrow specification are taken care of + automatically). See also Section~\ref{section-arrow-tip-macro} for + details on the order in which options get executed in such cases. + + Note that the \meta{end arrow specification} will be executed + immediately to build the so-called arrow option caches, a concept + explored in more detail in + Section~\ref{section-arrow-option-cache}. 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 \meta{end arrow + specification} will be evaluated immediately. For instance, when + you write + % \begin{codeexample}[code only] -\pgfdeclarearrow{ name=foo, means = bar[length=2cm+\mydimen] } +\pgfdeclarearrow{ name=foo, means = bar[length=2cm+\mydimen] } \end{codeexample} - The value |2cm+\mydimen| is evaluated immediately. When |foo| is - used later on and |\mydimen| has changed, this has no effect. - \end{itemize} + % + The value |2cm+\mydimen| is evaluated immediately. When |foo| is + used later on and |\mydimen| has changed, this has no effect. + \end{itemize} \end{command} - \subsection{Handling Arrow Options} - \label{section-arrow-options} -When you declare an arrow tip, your drawing code should take into -account the different arrow keys set for it (like the arrow tip length, -width, or harpooning). The different arrow keys that are available -have been described in detail in Section~\ref{section-arrow-config}; but -how do we access the values set by an option like |length| or -|harpoon| or |bend| in the drawing code? In the present section we -have a look at how this works. +When you declare an arrow tip, your drawing code should take into account the +different arrow keys set for it (like the arrow tip length, width, or +harpooning). The different arrow keys that are available have been described in +detail in Section~\ref{section-arrow-config}; but how do we access the values +set by an option like |length| or |harpoon| or |bend| in the drawing code? In +the present section we have a look at how this works. \subsubsection{Dimension Options} -Most arrow keys, like |length| or |width'|, simple set a \TeX\ -dimension register to a certain value. For example, |length| sets the -value of the \TeX\ dimension register |\pgfarrowlength|. Note that -|length| takes several values as input with a complicated semantics as -explained for the |length| key on -page~\pageref{length-arrow-key}. All of these settings are not -important for the setup code: When it gets executed, the code behind -the |length| key will have computed a simple number that is stored -in |\pgfarrowlength|. Indeed, inside the setup code you do not have -access to the exact value given to the |length| key; just to the -final computed value. +Most arrow keys, like |length| or |width'|, simple set a \TeX\ dimension +register to a certain value. For example, |length| sets the value of the \TeX\ +dimension register |\pgfarrowlength|. Note that |length| takes several values +as input with a complicated semantics as explained for the |length| key on +page~\pageref{length-arrow-key}. All of these settings are not important for +the setup code: When it gets executed, the code behind the |length| key will +have computed a simple number that is stored in |\pgfarrowlength|. Indeed, +inside the setup code you do not have access to the exact value given to the +|length| key; just to the final computed value. The following \TeX\ dimensions are available to the setup code: - +% \begin{itemize} -\item |\pgfarrowslength|. It gets set by the arrow keys |length| and |angle|. -\item |\pgfarrowswidth|. It gets set by |width|, |width'|, and |angle|. -\item |\pgfarrowsinset|. It gets set by |inset| and |inset'|. -\item |\pgfarrowslinewidth|. It gets set by |line width| and |line width'|. + \item |\pgfarrowslength|. It gets set by the arrow keys |length| and + |angle|. + \item |\pgfarrowswidth|. It gets set by |width|, |width'|, and |angle|. + \item |\pgfarrowsinset|. It gets set by |inset| and |inset'|. + \item |\pgfarrowslinewidth|. It gets set by |line width| and |line width'|. \end{itemize} -If your setup code depends on any of them, add them to the -|parameters| key of the arrow tip. +If your setup code depends on any of them, add them to the |parameters| key of +the arrow tip. \subsubsection{True--False Options} -A number of arrow keys just do a yes/no switch, like |reversed|. All -of them setup a \TeX-if that you can access in the setup code: - +A number of arrow keys just do a yes/no switch, like |reversed|. All of them +setup a \TeX-if that you can access in the setup code: +% \begin{itemize} -\item |\ifpgfarrowreversed| is setup by |reversed|. -\item |\ifpgfarrowswap| is setup by |swap| and also |right|. -\item |\ifpgfarrowharpoon| is setup by |harpoon| and also |left| and |right|. -\item |\ifpgfarrowroundcap| is set to true by |line cap=round| and set - to false by |line cap=butt|. It also gets (re)set by |round| and |sharp|. -\item |\ifpgfarrowroundjoin| is set to true by |line join=round| and set - to false by |line join=miter|. It also gets (re)set by |round| and |sharp|. -\item |\ifpgfarrowopen| is set to true by |fill=none| and by |open| - (which is a shorthand for |fill=none|) and set to false by |color| - and all other |fill=|\meta{color}. + \item |\ifpgfarrowreversed| is setup by |reversed|. + \item |\ifpgfarrowswap| is setup by |swap| and also |right|. + \item |\ifpgfarrowharpoon| is setup by |harpoon| and also |left| and + |right|. + \item |\ifpgfarrowroundcap| is set to true by |line cap=round| and set to + false by |line cap=butt|. It also gets (re)set by |round| and |sharp|. + \item |\ifpgfarrowroundjoin| is set to true by |line join=round| and set to + false by |line join=miter|. It also gets (re)set by |round| and + |sharp|. + \item |\ifpgfarrowopen| is set to true by |fill=none| and by |open| (which + is a shorthand for |fill=none|) and set to false by |color| and all + other |fill=|\meta{color}. \end{itemize} -If you code depends on any of these, you must add them to -the |parameters| in such a way that the parameters are different when -the \TeX-if is set from when it is not set. An easy way to achieve -this is to write something like +If you code depends on any of these, you must add them to the |parameters| in +such a way that the parameters are different when the \TeX-if is set from when +it is not set. An easy way to achieve this is to write something like +% \begin{codeexample}[code only] parameters = { \the\pgfarrowlength,..., \ifpgfarrowharpoon h\fi\ - \ifpgfarrowroundjoin j\fi} + \ifpgfarrowroundjoin j\fi} \end{codeexample} -In other words, for each set parameter on which the arrow tip depends, -a specific letter is added to the parameters, making them unique. +% +In other words, for each set parameter on which the arrow tip depends, a +specific letter is added to the parameters, making them unique. The first two of the above keys are a bit special: Reversing and swapping an -arrow tip can be done just by fiddling with the -transformation matrix: a reverse is a ``flip'' along the $y$-axis and -a swap is a flip along the $x$-axis. This is done automatically by -\pgfname. - -Nevertheless, you may wish to modify you code in dependence -especially of the |reverse| key: When |\ifpgfarrowreverse| is true, -\pgfname\ will flip the coordinate system along the $y$-axis, will -negate all end values (like line end, tip end, and so on) and will -exchange the meaning of back end and tip end as well as of visual back -end and visual back end. Usually, this is exactly what one need; -\emph{except} that the line end may no longer be appropriate. After -all, the line end should be chosen so that it is completely covered by -the arrow. Now, when the arrow tip is open, a reversed arrow should no -longer have the line end near the old visual back end, but near to the -old visual tip end. - -For these reasons, you may need to make the computation of the line -end dependent on whether the arrow is reversed or not. Note that when -you specify a different line end for a reversed arrow tip, the -transformation and inverting of the coordinate system will still be -done, meaning that if |reverse| is true, you need to specify a line -end in the ``old'' coordinate system that is at the position where, -after everything is inverted, it will be at the correct -position. Usually that means that if the |reverse| option is set, you -need to \emph{increase} the line end. +arrow tip can be done just by fiddling with the transformation matrix: a +reverse is a ``flip'' along the $y$-axis and a swap is a flip along the +$x$-axis. This is done automatically by \pgfname. + +Nevertheless, you may wish to modify you code in dependence especially of the +|reverse| key: When |\ifpgfarrowreverse| is true, \pgfname\ will flip the +coordinate system along the $y$-axis, will negate all end values (like line +end, tip end, and so on) and will exchange the meaning of back end and tip end +as well as of visual back end and visual back end. Usually, this is exactly +what one need; \emph{except} that the line end may no longer be appropriate. +After all, the line end should be chosen so that it is completely covered by +the arrow. Now, when the arrow tip is open, a reversed arrow should no longer +have the line end near the old visual back end, but near to the old visual tip +end. + +For these reasons, you may need to make the computation of the line end +dependent on whether the arrow is reversed or not. Note that when you specify a +different line end for a reversed arrow tip, the transformation and inverting +of the coordinate system will still be done, meaning that if |reverse| is true, +you need to specify a line end in the ``old'' coordinate system that is at the +position where, after everything is inverted, it will be at the correct +position. Usually that means that if the |reverse| option is set, you need to +\emph{increase} the line end. \subsubsection{Inaccessible Options} -There are some options that influence the way an arrow tip looks, but -that you cannot access inside the setup code. Handling these options -lies entirely with \pgfname. If you wish your setup code to handle -these options, you have to setup your own ``parallel'' options. - +There are some options that influence the way an arrow tip looks, but that you +cannot access inside the setup code. Handling these options lies entirely with +\pgfname. If you wish your setup code to handle these options, you have to +setup your own ``parallel'' options. +% \begin{itemize} -\item |quick|, |flex|, |flex'|, and |bend| are all handled - automatically. You can, however, set the |bending mode| to avoid - bending of your arrow tip. -\item The colors set by |color| and |fill|. You can, however, access - them indirectly, namely through the current stroke and fill colors. -\item |sep| + \item |quick|, |flex|, |flex'|, and |bend| are all handled automatically. + You can, however, set the |bending mode| to avoid bending of your arrow + tip. + \item The colors set by |color| and |fill|. You can, however, access them + indirectly, namely through the current stroke and fill colors. + \item |sep| \end{itemize} \subsubsection{Defining New Arrow Keys} \label{section-arrow-option-cache} -The set of predefined options is already quite long and most arrow -tips will not need more than the predefined options. However, -sometimes an arrow tip may need to introduce a new special-purpose -option. For instance, suppose we wish to introcue a new fictive arrow -key |depth|. In such cases, you must do two things: - +The set of predefined options is already quite long and most arrow tips will +not need more than the predefined options. However, sometimes an arrow tip may +need to introduce a new special-purpose option. For instance, suppose we wish +to introduce a new fictive arrow key |depth|. In such cases, you must do two +things: +% \begin{enumerate} -\item - Introduce a new dimension register or macro that will hold the - configuration value and which will be accessed by the setup - code. The could be achieved by saying + \item Introduce a new dimension register or macro that will hold the + configuration value and which will be accessed by the setup code. The + could be achieved by saying + % \begin{codeexample}[code only] \newdimen\pgfarrowdepth \end{codeexample} -\item - Introduce a new arrow key option |/pgf/arrow keys/depth| that allows - users to configure the new macro or register. + % + \item Introduce a new arrow key option |/pgf/arrow keys/depth| that allows + users to configure the new macro or register. \end{enumerate} -When an arrow is selected via for instance |foo[depth=5pt]|, the -key--value pairs between the square brackets are executed with the -path prefix |/pgf/arrow keys|. Thus, in the example, our depth key -would get executed. Thus, it is temping to write something like +When an arrow is selected via for instance |foo[depth=5pt]|, the key--value +pairs between the square brackets are executed with the path prefix +|/pgf/arrow keys|. Thus, in the example, our depth key would get executed. +Thus, it is tempting to write something like +% \begin{codeexample}[code only] \pgfkeys{/pgf/arrow keys/depth/.code = \pgfmathsetlength{\pgfarrowdepth}{#1}} \end{codeexample} -Sadly, this will not work. The reason is that the is yet another level -of caching involved when \pgfname\ processes arrow tips: The option -cache! The problem is each time an arrow tip is used, even when the -drawing code of the arrow tip is nicely cached, we still need to -process the options in |foo[length=5pt]| to find out which version in -the cache we would like to access. To make matters worse, |foo| might -be a shorthand that calls other arrow tips, which add more options, -and so on. Unfortunately, executing keys is quite an expensive -operation (\pgfname's key--value parser is powerful, but that power -comes at a price). So, whenever possible, we do \emph{not} want the +Sadly, this will not work. The reason is that there is yet another level of +caching involved when \pgfname\ processes arrow tips: The option cache! The +problem is each time an arrow tip is used, even when the drawing code of the +arrow tip is nicely cached, we still need to process the options in +|foo[length=5pt]| to find out which version in the cache we would like to +access. To make matters worse, |foo| might be a shorthand that calls other +arrow tips, which add more options, and so on. Unfortunately, executing keys is +quite an expensive operation (\pgfname's key--value parser is powerful, but +that power comes at a price). So, whenever possible, we do \emph{not} want the key--value parser to be started. -For these reasons, when something like |foo[|\meta{options}|]| is -encountered inside a shorthand, the \meta{options} are executed only -once. They should now setup the \emph{arrow option cache}, which is -some code that, when executed, should setup the values that the -\meta{options} configure. In our example, the |depth| key should add -something to the arrow option cache that sets |\pgfarrowdepth| to the -given value. +For these reasons, when something like |foo[|\meta{options}|]| is encountered +inside a shorthand, the \meta{options} are executed only once. They should now +setup the \emph{arrow option cache}, which is some code that, when executed, +should setup the values that the \meta{options} configure. In our example, the +|depth| key should add something to the arrow option cache that sets +|\pgfarrowdepth| to the given value. -Adding something to the arrow option cache is done using the following -command: +Adding something to the arrow option cache is done using the following command: \begin{command}{\pgfarrowsaddtooptions\marg{code}} - 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: + 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: + % \begin{codeexample}[code only] \pgfkeys{/pgf/arrow keys/depth/.code= \pgfarrowsaddtooptions{\pgfmathsetlength{\pgfarrowdepth}{#1}} \end{codeexample} - 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: + % + 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: + % \begin{codeexample}[code only] \pgfkeys{/pgf/arrow keys/depth/.code= \pgfmathsetlength{\somedimen}{#1} \pgfarrowsaddtooptions{\pgfarrowdepth=\somedimen} % buggy \end{codeexample} - 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: + % + 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: + % \begin{codeexample}[code only] \pgfkeys{/pgf/arrow keys/depth/.code= \pgfmathsetlength{\somedimen}{#1} \expandafter\pgfarrowsaddtooptions\expandafter{\expandafter\pgfarrowdepth\expandafter=\the\somedimen} \end{codeexample} + % \end{command} \begin{command}{\pgfarrowsaddtolateoptions\marg{code}} - This command works like |\pgfarrowsaddtooptions|, only the - \meta{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. + This command works like |\pgfarrowsaddtooptions|, only the \meta{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. \end{command} -If you define a new option that sets a dimensions and if that -dimension should change in accordance to the setting of either -|scale length| or |scale width|, you need to make \pgfname\ ``aware'' -of this using the following key: +If you define a new option that sets a dimensions and if that dimension should +change in accordance to the setting of either |scale length| or |scale width|, +you need to make \pgfname\ ``aware'' of this using the following key: \begin{command}{\pgfarrowsaddtolengthscalelist\marg{dimension register}} - Each time an arrow tip is used, the given \meta{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. + Each time an arrow tip is used, the given \meta{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. \end{command} \begin{command}{\pgfarrowsaddtowidthscalelist\marg{dimension register}} - Works like |\pgfarrowsaddtolengthscalelist|, only for width parameters. + Works like |\pgfarrowsaddtolengthscalelist|, only for width parameters. \end{command} -\begin{command}{\pgfarrowsthreeparameters\marg{line-width dependent - size specification}} - 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 \meta{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} - } +\begin{command}{\pgfarrowsthreeparameters\marg{line-width dependent size specification}} + 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 \meta{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} + } \begin{codeexample}[] \pgfarrowsthreeparameters{2pt 1} -\showvalueofmacro\pgfarrowstheparameters +\showvalueofmacro\pgfarrowstheparameters \end{codeexample} + % \end{command} +\begin{command}{\pgfarrowslinewidthdependent\marg{dimension}\marg{line width factor}\marg{outer factor}} + This command take three parameters and does the ``line width dependent + computation'' described on page~\pageref{length-arrow-key} for the |length| + key. The result is returned in |\pgf@x|. -\begin{command}{\pgfarrowslinewidthdependent\marg{dimension}\marg{line - width factor}\marg{outer factor}} - This command take three parameters and does the ``line width - dependent computation'' described on page~\pageref{length-arrow-key} - 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: + The idea is that you can setup line-width dependent keys like |length| or + |width| using code like the following: + % \begin{codeexample}[code only] \pgfkeys{/pgf/arrow keys/depth/.code={% \pgfarrowsthreeparameters{#1}% @@ -877,16 +872,18 @@ of this using the following key: \expandafter\pgfarrowslinewidthdependent\pgfarrowstheparameters% compute... \pgfarrowdepth\pgf@x% ... and store. }% -} +} \end{codeexample} + % \end{command} \begin{command}{\pgfarrowslengthdependent\marg{dimension}\marg{length factor}\marg{dummy}} - This command take 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|. + This command take 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: + You can setup length dependent keys using code like the following: + % \begin{codeexample}[code only] \pgfkeys{/pgf/arrow keys/depth'/.code={% \pgfarrowsthreeparameters{#1}% @@ -894,8 +891,9 @@ of this using the following key: \expandafter\pgfarrowslengthdependent\pgfarrowstheparameters% compute... \pgfarrowdepth\pgf@x% ... and store. }% -} +} \end{codeexample} + % \end{command} |