summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex124
1 files changed, 99 insertions, 25 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex
index 3739db4d83b..7030e1f96ac 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex
@@ -12,6 +12,7 @@
\makeatletter
+
\subsection{Beginning and Ending a Stream of System Commands}
A ``user'' of the \pgfname\ system layer (like the basic layer or a
@@ -33,13 +34,13 @@ command.
\begin{command}{\pgfsys@beginpicture}
Called at the beginning of a |{pgfpicture}|. This command should
- ``setup things.''
+ ``set up things.''
Most drivers will need to implement this command.
\end{command}
\begin{command}{\pgfsys@endpicture}
- Called at the end of a pgfpicture.
+ Called at the end of a |{pgfpicture}|.
Most drivers will need to implement this command.
\end{command}
@@ -101,6 +102,19 @@ force. For this escaping, the following command is used:
implementation, where a \TeX-translation makes no sense.
\end{command}
+\begin{command}{\pgfsys@pictureboxsynced\marg{box number}}
+ Basically, this should do the same as doing a (scoped) low level sync
+ followed by inserting the box \meta{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
+ \textsc{pdf}s. Drivers that are sensitive to picture-in-picture
+ scopes should replace this implementation by
+\begin{codeexample}[code only]
+\pgfsys@beginscope\pgflowlevelsynccm\box#1\pgfsys@endscope
+\end{codeexample}
+\end{command}
+
\subsection{Path Construction System Commands}
@@ -139,7 +153,7 @@ force. For this escaping, the following command is used:
\begin{command}{\pgfsys@curveto\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}\marg{$x_3$}\marg{$y_3$}}
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)$.
+ with a B\'ezier curve that has the two control points $(x_1,y_1)$ and $(x_2,y_2)$.
\example Draw a good approximation of a quarter circle:
\begin{codeexample}[code only]
@@ -429,14 +443,13 @@ force. For this escaping, the following command is used:
\begin{command}{\pgfsys@setdash\marg{pattern}\marg{phase}}
Sets the dashing patter. \meta{pattern} should be a list of \TeX\
- dimensions lengths separated by commas. \meta{phase} should be a
+ dimensions separated by commas. \meta{phase} should be a
single dimension.
\example |\pgfsys@setdash{3pt,3pt}{0pt}|
The list of values in \meta{pattern} is used to determine the
- lengths of the ``on'' phases of the dashing and of the ``off''
- phases. For example, if \meta{pattern} is |3bp,4bp|, then the dashing
+ lengths of the ``on'' and ``off'' phases of the dashing. For example, if \meta{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, \dots'' If the
@@ -508,20 +521,20 @@ whenever a stroking or a filling operation is done.
\begin{command}{\pgfsys@color@cmyk\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}}
Sets the color used for stroking and filling operations to the given
- cymk tuple (numbers between 0 and 1).
+ cmyk tuple (numbers between 0 and 1).
This command is protocolled, see Section~\ref{section-protocols}.
\end{command}
\begin{command}{\pgfsys@color@cmyk@stroke\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}}
- Sets the color used for stroking operations to the given cymk tuple
+ Sets the color used for stroking operations to the given cmyk tuple
(numbers between 0 and 1).
This command is protocolled, see Section~\ref{section-protocols}.
\end{command}
\begin{command}{\pgfsys@color@cmyk@fill\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}}
- Sets the color used for filling operations to the given cymk tuple
+ Sets the color used for filling operations to the given cmyk tuple
(numbers between 0 and 1).
This command is protocolled, see Section~\ref{section-protocols}.
@@ -529,20 +542,20 @@ whenever a stroking or a filling operation is done.
\begin{command}{\pgfsys@color@cmy\marg{cyan}\marg{magenta}\marg{yellow}}
Sets the color used for stroking and filling operations to the given
- cymk tuple (numbers between 0 and 1).
+ cmy tuple (numbers between 0 and 1).
This command is protocolled, see Section~\ref{section-protocols}.
\end{command}
\begin{command}{\pgfsys@color@cmy@stroke\marg{cyan}\marg{magenta}\marg{yellow}}
- Sets the color used for stroking operations to the given cymk tuple
+ Sets the color used for stroking operations to the given cmy tuple
(numbers between 0 and 1).
This command is protocolled, see Section~\ref{section-protocols}.
\end{command}
\begin{command}{\pgfsys@color@cmy@fill\marg{cyan}\marg{magenta}\marg{yellow}}
- Sets the color used for filling operations to the given cymk tuple
+ Sets the color used for filling operations to the given cmy tuple
(numbers between 0 and 1).
This command is protocolled, see Section~\ref{section-protocols}.
@@ -718,7 +731,7 @@ The system layer provides some commands for image inclusion.
If this macro and also the height macro are empty, the image
should have its ``natural'' size.
- If exactly only of them is specified, the undefined value the
+ 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
@@ -743,7 +756,7 @@ The system layer provides some commands for image inclusion.
interpolated in \pdf.
\end{itemize}
- The command should now setup the macro |\pgf@image| such that calling
+ 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.
@@ -784,7 +797,7 @@ The system layer provides some commands for image inclusion.
\begin{command}{\pgfsys@radialshading\marg{name}\marg{starting point}\marg{specification}}
Declares a radial shading. Like the previous macros, this command
- should setup the macro |\@pgfshading|\meta{name}|!|, which upon
+ should set up the macro |\@pgfshading|\meta{name}|!|, which upon
invocation should insert a radial shading whose size is implicit in
\meta{specification}.
@@ -797,22 +810,22 @@ The system layer provides some commands for image inclusion.
corner}\meta{upper right corner}\marg{type 4 function}}
Declares a shading using a PostScript-like function that provides a
color for each point. Like the previous macros, this command
- should setup the macro |\@pgfshading|\meta{name}|!| so that it will
+ should set up the macro |\@pgfshading|\meta{name}|!| so that it will
produce a box containing the desired shading.
Parameter \meta{name} is the name of the shading. Parameter
\meta{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.
+ as described in Section 3.9.4 of the PDF specification version 1.7.
Parameters \meta{lower left corner} and \meta{upper right corner} are
\pgfname\ points that specifies the lower left and upper right
- corners of the shading.
+ corners of the shading, respectively.
When \meta{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 cvr's at the end if needed) that represent the red,
+ 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 \emph{totally unpredictable chaos} during
@@ -831,8 +844,13 @@ The system layer provides some commands for image inclusion.
Sets the opacity of filling operations.
\end{command}
+\begin{command}{\pgfsys@blend@mode\marg{value}}
+ Sets the blend mode, see Section 7.2.4 of the \textsc{pdf}
+ Specification, Version 1.7.
+\end{command}
+
\begin{command}{\pgfsys@transparencygroupfrombox\marg{box}}
- This takes a TeX box and converts it into a transparency
+ 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
@@ -841,9 +859,29 @@ The system layer provides some commands for image inclusion.
group, the overlap will get the same color as the rest.
\end{command}
+A transparency group can be \emph{isolated} and/or a \emph{knockout}
+group (see Sections 7.3.4 and 7.3.5 of the \textsc{pdf}
+Specification Version 1.7). Which of these is the case is dictated
+by the current settings of the following two ifs, which must be set
+before the above command is called:
+
+{\let\ifpgfsys@transparency@group@isolated=\relax
+\begin{command}{\ifpgfsys@transparency@group@isolated}
+ Determines whether a transparency group should be isolated.
+\end{command}
+}
+
+{\let\ifpgfsys@transparency@group@knockout=\relax
+\begin{command}{\ifpgfsys@transparency@group@knockout}
+ Determines whether a transparency group is a knockout group or not.
+\end{command}
+}
+
+
+
\begin{command}{\pgfsys@fadingfrombox\marg{name}\marg{box}}
Declares the fading \meta{name}. The \meta{box} is a \TeX-box. Its
- contents luminosity determines the opacity of the resulting
+ 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.
\end{command}
@@ -950,11 +988,47 @@ commands do not open a graphics scope and can be opened and closed
\end{command}
+
+\subsection{Page Size Commands}
+
+The following commands can be used to set the page size of a document
+in a ``portable'' way. Note, however, that many packages also (try to)
+set the page size.
+
+These commands are typically not given inside a |{pgfpicture}|, but on
+the outer level of compilation.
+
+\begin{command}{\pgfsys@papersize\marg{width}\marg{height}}
+ 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.
+\end{command}
+
+\begin{command}{\pgfsys@global@papersize\marg{width}\marg{height}}
+ 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.
+\end{command}
+
+\begin{command}{\pgfsys@thepageheight}
+ This macro expands to the current page's height, provided \LaTeX\ is
+ used, otherwise a best guess is returned (currently just |\the\vsize|).
+\end{command}
+
+\begin{command}{\pgfsys@thepagewidth}
+ As above.
+\end{command}
+
\subsection{Position Tracking Commands}
The following commands are used to determine the position of text on a
page. This is a rather complicated process in general since at the
-moment when the text is read by \TeX\ the final position cannot be
+moment when the text is read by \TeX, the final position cannot be
determined, yet. For example, the text might be put in a box which is
later put in the headline or perhaps in the footline or perhaps even
on a different page.
@@ -963,7 +1037,7 @@ For these reasons, position tracking is typically a two-stage
process. In a first stage you indicate that a certain position is of
interest by \emph{marking} it. This will (depending on the details of
the backend driver) cause page coordinates or this position to be
-written to a |.aux| file when the page is shipped. Possibly, the
+written to an |.aux| file when the page is shipped. Possibly, the
position might also be determined at an even later stage. Then, on a
second run of \TeX, the position is read from the |.aux| file and can
be used.
@@ -981,7 +1055,7 @@ The value of $x$ is \pgfsys@markposition{here}important.
\begin{command}{\pgfsys@getposition\marg{name}\marg{macro}}
This command retrieves a position that has been marked on an earlier
run of \TeX\ on the current file. The \meta{macro} must be a macro
- name such as |\mymarco|. It will redefined such that it is
+ name such as |\mymacro|. It will be redefined such that it is
\begin{itemize}
\item either just |\relax| or
\item a |\pgfpoint...| command.
@@ -1002,7 +1076,7 @@ The value of $x$ is \pgfsys@markposition{here}important.
|pgfpageorigin|. By shifting all positions by the amount returned by
this call you can position things absolutely on a page.
- \example Referencing a point or the page:
+ \example Referencing a point of the page:
\begin{codeexample}[code only]
The value of $x$ is \pgfsys@markposition{here}important.