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 | 162 |
1 files changed, 139 insertions, 23 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 4f5033ec86a..aac739b9d1f 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 @@ -22,7 +22,7 @@ of lines. The interface works as follows: \begin{enumerate} \item You (or someone else) assigns a name to a certain kind of arrow - tips. For example, the + tips. For example, the arrow tip |latex| is the arrow tip used by the standard \LaTeX\ picture environment; the arrow tip |to| looks like the tip of the arrow in \TeX's |\to| command; and so on. @@ -49,6 +49,7 @@ of lines. The interface works as follows: In the above description, there are a number of ``appropriately.'' The exact details are not quite trivial and described later on. + \subsubsection{Meta-Arrow Tips} In \pgfname, arrows are ``meta-arrows'' in the same way that fonts in @@ -69,7 +70,7 @@ 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. +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 the line width of the arrow tip is @@ -96,7 +97,7 @@ drawn by \pgfname\ at four different sizes: \medskip Here, by comparison, is the same arrow when it is simply ``resized'' -(as done by most programs): +(as done by some programs): \pgfarrowsdeclare{bad latex}{bad latex} { @@ -156,6 +157,11 @@ Here, by comparison, is the same arrow when it is simply ``resized'' 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. + \subsection{Declaring an Arrow Tip Kind} @@ -259,8 +265,8 @@ used: \item The code will be executed only once, namely the first time the arrow tip needs to be drawn. The resulting low-level driver - commands are protocoled and stored away. In all subsequent - uses of the arrow tip, the protocoled code is directly inserted. + commands are protocolled and stored away. In all subsequent + uses of the arrow tip, the protocolled code is directly inserted. \item However, the code will be executed anew for each line width. Thus, an arrow of line width 2pt may result in a different protocol than @@ -287,7 +293,7 @@ used: larger. However, the size of the arrow typically \emph{should not} grow in direct proportion to the line width. On the other hand, the size of the arrow head typically \emph{should} grow ``a bit'' with - the line width. + the line width. For these reasons, \pgfname\ will not simply executed your arrow code within a scaled scope, where the scaling depends on the line @@ -297,7 +303,7 @@ used: In our example, we could use the following code for the new arrow tip kind |arc'| (note the prime): \begin{codeexample}[code only] -\newdimen\arrowsize +\newdimen\arrowsize \pgfarrowsdeclare{arcs'}{arcs'}{...} { \arrowsize=0.2pt @@ -311,7 +317,7 @@ used: \pgfusepathqstroke } \end{codeexample} -\newdimen\arrowsize +\newdimen\arrowsize \pgfarrowsdeclare{arcs'}{arcs'}{\pgfarrowsleftextend{0pt}\pgfarrowsrightextend{0pt}} { \arrowsize=0.2pt @@ -333,7 +339,7 @@ used: \useasboundingbox (-2,-1.75) rectangle (0,0.5); \end{tikzpicture} \end{codeexample} - + However, sometimes, it can also be useful to have arrows that do not resize at all when the line width changes. This can be achieved by giving absolute size coordinates in the code, as done for |arc|. On @@ -341,6 +347,7 @@ used: line width by specifying all coordinates as multiples of |\pgflinewidth|. + \medskip \textbf{The left and right extend.} Let us have another look at the exact left and right ``ends'' of our arrow tip. Let us draw the arrow tip |arc'| at a very large size: @@ -384,13 +391,13 @@ used: \coordinate (xline 1) at (0,1.5); \coordinate (xline 2) at (0,2.8); - - \draw[|->|] (xline 1 -| a) -- node[above=2pt] {right extend} (xline 1 -| b); + + \draw[|->|] (xline 1 -| a) -- node[above=2pt] {right extend} (xline 1 -| b); \draw[|<-|] (xline 2 -| c) -- node[above=2pt] {left extend} (xline 2 -| a); \draw (0,0) -- (1,-1) node[below right] {origin}; \end{tikzpicture} - + The \meta{extend code} is normal \TeX\ code that is executed whenever \pgfname\ wants to know how far the arrow tip will protrude @@ -398,7 +405,7 @@ used: commands: \declare{|\pgfarrowsrightextend|} and \declare{|\pgfarrowsleftextend|}. Both arguments take one argument that specifies the size. Here is the final code for the |arc''| arrow - tip: + tip: \begin{codeexample}[] \pgfarrowsdeclare{arcs''}{arcs''} { @@ -426,6 +433,104 @@ used: \draw[line width=2pt,white] (-2,0) -- (0,0); \end{tikzpicture} \end{codeexample} + + \medskip + \textbf{Taking inner lines into account.} + In addition to the line width, there is another parameter that (may) + influence the way an arrow looks: The inner line width, which is the + line width of the second line that is stroked on top of a normal + line in order to create the effect of a ``double'' line. When this + line width changes, the arrow tip code is also reexecuted (and + cached), so your code may depend on the current value of the inner + line width. + + The following example shows how this works. The |implies| arrow + defined below has to setup the line width not for the ``main'' line + width, but for the main line width minus the inner line width, + divided by~2. +\begin{codeexample}[code only] +\pgfarrowsdeclare{implies}{implies}{...} +{ + \pgfmathsetlength{\pgfutil@tempdimb}{.5\pgflinewidth-.5*\pgfinnerlinewidth}% + \pgfsetlinewidth{\pgfutil@tempdimb} + \pgfsetdash{}{0pt} + \pgfsetroundcap + \pgfsetroundjoin + \pgfmathsetlength{\pgfutil@tempdima}{.25\pgflinewidth+.25*\pgfinnerlinewidth}% + \pgfpathmoveto {\pgfpoint{-1.4\pgfutil@tempdima}{2.65\pgfutil@tempdima}} + \pgfpathcurveto{\pgfpoint{-0.75\pgfutil@tempdima}{1.25\pgfutil@tempdima}} + {\pgfpoint{1\pgfutil@tempdima}{0.05\pgfutil@tempdima}} + {\pgfpoint{2\pgfutil@tempdima}{0pt}} + \pgfpathcurveto{\pgfpoint{1\pgfutil@tempdima}{-0.05\pgfutil@tempdima}} + {\pgfpoint{-.75\pgfutil@tempdima}{-1.25\pgfutil@tempdima}} + {\pgfpoint{-1.4\pgfutil@tempdima}{-2.65\pgfutil@tempdima}} + \pgfusepathqstroke +} +\end{codeexample} + Here is the effect for different combinations of line width and + inner line width: +\begin{codeexample}[] +\begin{tikzpicture} + \foreach \linewidth in {2,2.4,...,4.4} + \foreach \innerlinewidth in {0.4,0.8,...,1.8} + { + \pgfsetlinewidth{\linewidth pt} + \pgfsetinnerlinewidth{\innerlinewidth pt} + \draw [-implies] (\innerlinewidth*50pt,\linewidth*40pt) -- ++(4mm,0); + } +\end{tikzpicture} +\end{codeexample} + + \medskip + \textbf{Arrow options.} + You may wish to have further option influence the appearance of an + arrow tip. For instance, for a ``pointed'' arrow you may wish to set + the opening angle of the tip. Then, whenever this option changes + that arrow tip code also needs to be reexecuted, even though the + line width has stayed the same. + + You can use the commands |\pgfsetarrowoptions| and + |\pgfgetarrowoptions| to set such options for an arrow tip. Whenever + an arrow tip needs to be rendered, it is checked whether the arrow + tip code has already been executed for the current (expanded) value of the + options. If so, the cached code is used; otherwise the code is + executed once more. Naturally, inside the code the current value of + the arrow options should be taken into account. + + Arrow options can and must be specified individually for each arrow + type. + + In the following example, we make the arc angle an option. +\begin{codeexample}[] +\pgfarrowsdeclare{var arc}{var arc} % options is an angle +{ + \arrowsize=0.2pt + \advance\arrowsize by .5\pgflinewidth + \pgfarrowsleftextend{-4\arrowsize-.5\pgflinewidth} + \pgfarrowsrightextend{.5\pgflinewidth} +} +{ + \arrowsize=0.2pt + \advance\arrowsize by .5\pgflinewidth + \pgfsetdash{}{0pt} % do not dash + \pgfsetroundjoin % fix join + \pgfsetroundcap % fix cap + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharc{-90}{-180+\pgfgetarrowoptions{var arc}}{4\arrowsize} + \pgfusepathqstroke + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharc{90}{180-\pgfgetarrowoptions{var arc}}{4\arrowsize} + \pgfusepathqstroke +} +\begin{tikzpicture} + \draw[help lines] (-2,-4) grid (1,4); + \foreach \option in {-60,-50,...,60} + { + \pgfsetarrowoptions{var arc}{\option} + \draw[ultra thick,-var arc] (-2,\option/15) -- (0,\option/15); + } +\end{tikzpicture} +\end{codeexample} \end{command} \pgfarrowsdeclare{arcs''}{arcs''} @@ -449,6 +554,17 @@ used: \pgfusepathqstroke } +\begin{command}{\pgfsetarrowoptions\marg{arrow tip}\marg{text}} + Sets the options for the \meta{arrow tip} to \meta{text}. The + default, before any call to this macro is made, is 0. +\end{command} + +\begin{command}{\pgfgetarrowoptions\marg{arrow tip}} + This will expand to the current value of the options for the + \meta{arrow tip}. +\end{command} + + \subsection{Declaring a Derived Arrow Tip Kind} @@ -480,7 +596,7 @@ set correctly. This command creates a new arrow kind that is the ``reverse'' of an existing arrow kind. The (automatically cerated) code of the new arrow kind will contain a flip of the canvas and the meanings of the - left and right extend will be reversed. + left and right extend will be reversed. \begin{codeexample}[] \pgfarrowsdeclarereversed{arcs reversed}{arcs reversed}{arcs''}{arcs''}% @@ -557,7 +673,7 @@ set correctly. \pgfusepath{stroke} \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); \end{tikzpicture} -\end{codeexample} +\end{codeexample} \end{command} @@ -577,7 +693,7 @@ set correctly. \pgfusepath{stroke} \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); \end{tikzpicture} -\end{codeexample} +\end{codeexample} \end{command} @@ -603,7 +719,7 @@ stroking is done. \pgfusepath{stroke} \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); \end{tikzpicture} -\end{codeexample} +\end{codeexample} \end{command} \begin{command}{\pgfsetarrowsend\marg{start arrow kind}} @@ -617,11 +733,11 @@ stroking is done. \pgfusepath{stroke} \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); \end{tikzpicture} -\end{codeexample} +\end{codeexample} \end{command} \emph{Warning:} If the compatibility mode is active (which is the -default), there also exist old commands called |\pgfsetstartarrow| and +default), there also exist old commands called |\pgfsetstartarrow| and |\pgfsetendarrow|, which are incompatible with the meta-arrow management. @@ -638,7 +754,7 @@ management. \pgfusepath{stroke} \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); \end{tikzpicture} -\end{codeexample} +\end{codeexample} \end{command} @@ -660,7 +776,7 @@ The following arrow tip kinds are always defined: \sarrow{latex reversed}{latex reversed} \\ \index{*vbar@\protect\texttt{\protect\myvbar} arrow tip}% \index{Arrow tips!*vbar@\protect\texttt{\protect\myvbar}} - \texttt{|-|}& yields thick + \texttt{|-|}& yields thick \begin{tikzpicture}[arrows={|-|},thick] \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); \draw (0,0) -- (1,0); @@ -674,7 +790,7 @@ The following arrow tip kinds are always defined: For further arrow tips, see page~\pageref{section-library-arrows}. -%%% Local Variables: +%%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual" -%%% End: +%%% End: |