diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex')
| -rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex | 141 |
1 files changed, 67 insertions, 74 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex index 0f1c9e1eb02..65ec0f8896a 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex @@ -9,95 +9,91 @@ \section{Layered Graphics} - \label{section-layers} \subsection{Overview} -\pgfname\ provides a layering mechanism for composing graphics from -multiple layers. (This mechanism is not to be confused with the -conceptual ``software layers'' the \pgfname\ system is composed of.) -Layers are often used in graphic programs. The idea is that you can -draw on the different layers in any order. So you might start drawing -something on the ``background'' layer, then something on the -``foreground'' layer, then something on the ``middle'' layer, and then -something on the background layer once more, and so on. At the end, no -matter in which ordering you drew on the different layers, the layers -are ``stacked on top of each other'' in a fixed ordering to produce -the final picture. Thus, anything drawn on the middle layer would come -on top of everything of the background layer. - -Normally, you do not need to use different layers since you will have -little trouble ``ordering'' your graphic commands in such a way that -layers are superfluous. However, in certain situations you only -``know'' what you should draw behind something else after the -``something else'' has been drawn. - -For example, suppose you wish to draw a yellow background behind your -picture. The background should be as large as the bounding box of the -picture, plus a little border. If you know the size of the bounding box -of the picture at its beginning, this is easy to accomplish. However, -in general this is not the case and you need to create a -``background'' layer in addition to the standard ``main'' layer. Then, -at the end of the picture, when the bounding box has been established, -you can add a rectangle of the appropriate size to the picture. - +\pgfname\ provides a layering mechanism for composing graphics from multiple +layers. (This mechanism is not to be confused with the conceptual ``software +layers'' the \pgfname\ system is composed of.) Layers are often used in graphic +programs. The idea is that you can draw on the different layers in any order. +So you might start drawing something on the ``background'' layer, then +something on the ``foreground'' layer, then something on the ``middle'' layer, +and then something on the background layer once more, and so on. At the end, no +matter in which ordering you drew on the different layers, the layers are +``stacked on top of each other'' in a fixed ordering to produce the final +picture. Thus, anything drawn on the middle layer would come on top of +everything of the background layer. + +Normally, you do not need to use different layers since you will have little +trouble ``ordering'' your graphic commands in such a way that layers are +superfluous. However, in certain situations you only ``know'' what you should +draw behind something else after the ``something else'' has been drawn. + +For example, suppose you wish to draw a yellow background behind your picture. +The background should be as large as the bounding box of the picture, plus a +little border. If you know the size of the bounding box of the picture at its +beginning, this is easy to accomplish. However, in general this is not the case +and you need to create a ``background'' layer in addition to the standard +``main'' layer. Then, at the end of the picture, when the bounding box has been +established, you can add a rectangle of the appropriate size to the picture. \subsection{Declaring Layers} -In \pgfname\ layers are referenced using names. The standard layer, -which is a bit special in certain ways, is called |main|. If nothing -else is specified, all graphic commands are added to the |main| -layer. You can declare a new layer using the following command: +In \pgfname\ layers are referenced using names. The standard layer, which is a +bit special in certain ways, is called |main|. If nothing else is specified, +all graphic commands are added to the |main| layer. You can declare a new layer +using the following command: \begin{command}{\pgfdeclarelayer\marg{name}} - This command declares a layer named \meta{name} for later - use. Mainly, this will set up some internal bookkeeping. + This command declares a layer named \meta{name} for later use. Mainly, this + will set up some internal bookkeeping. \end{command} -The next step toward using a layer is to tell \pgfname\ which layers -will be part of the actual picture and which will be their -ordering. Thus, it is possible to have more layers declared than are -actually used. +The next step toward using a layer is to tell \pgfname\ which layers will be +part of the actual picture and which will be their ordering. Thus, it is +possible to have more layers declared than are actually used. \begin{command}{\pgfsetlayers\marg{layer list}} - This command tells \pgfname\ which layers will be used in - pictures. They are stacked on top of each other in the order - given. The layer |main| should always be part of the list. Here is - an example: + This command tells \pgfname\ which layers will be used in pictures. They + are stacked on top of each other in the order given. The layer |main| + should always be part of the list. Here is an example: + % \begin{codeexample}[code only] \pgfdeclarelayer{background} -\pgfdeclarelayer{foreground} +\pgfdeclarelayer{foreground} \pgfsetlayers{background,main,foreground} \end{codeexample} - This command should be given either outside of any picture or ``directly inside'' of a picture. - Here, the ``directly inside'' means that there should be no further level of \TeX\ grouping between |\pgfsetlayers| and the matching |\end{pgfpicture}| (no closing braces, no |\end{...}|). It will also work if |\pgfsetlayers| is provided before |\end{tikzpicture}| (with similar restrictions). + This command should be given either outside of any picture or ``directly + inside'' of a picture. Here, the ``directly inside'' means that there + should be no further level of \TeX\ grouping between |\pgfsetlayers| and + the matching |\end{pgfpicture}| (no closing braces, no |\end{...}|). It + will also work if |\pgfsetlayers| is provided before |\end{tikzpicture}| + (with similar restrictions). \end{command} \subsection{Using Layers} -Once the layers of your picture have been declared, you can start to -``fill'' them. As said before, all graphics commands are normally -added to the |main| layer. Using the |{pgfonlayer}| environment, you -can tell \pgfname\ that certain commands should, instead, be added to -the given layer. +Once the layers of your picture have been declared, you can start to ``fill'' +them. As said before, all graphics commands are normally added to the |main| +layer. Using the |{pgfonlayer}| environment, you can tell \pgfname\ that +certain commands should, instead, be added to the given layer. \begin{environment}{{pgfonlayer}\marg{layer name}} - The whole \meta{environment contents} is added to the layer with the - name \meta{layer name}. This environment can be used anywhere inside - a picture. Thus, even if it is used inside a |{pgfscope}| or a \TeX\ - group, the contents will still be added to the ``whole'' picture. - Using this environment multiple times inside the same picture will - cause the \meta{environment contents} to accumulate. - - \emph{Note:} You can \emph{not} add anything to the |main| layer - using this environment. The only way to add anything to the main - layer is to give graphic commands outside all |{pgfonlayer}| - environments. - + The whole \meta{environment contents} is added to the layer with the name + \meta{layer name}. This environment can be used anywhere inside a picture. + Thus, even if it is used inside a |{pgfscope}| or a \TeX\ group, the + contents will still be added to the ``whole'' picture. Using this + environment multiple times inside the same picture will cause the + \meta{environment contents} to accumulate. + + \emph{Note:} You can \emph{not} add anything to the |main| layer using this + environment. The only way to add anything to the main layer is to give + graphic commands outside all |{pgfonlayer}| environments. + % \begin{codeexample}[] \pgfdeclarelayer{background layer} \pgfdeclarelayer{foreground layer} @@ -105,15 +101,15 @@ the given layer. \begin{tikzpicture} % On main layer: \fill[blue] (0,0) circle (1cm); - + \begin{pgfonlayer}{background layer} \fill[yellow] (-1,-1) rectangle (1,1); \end{pgfonlayer} - + \begin{pgfonlayer}{foreground layer} \node[white] {foreground}; \end{pgfonlayer} - + \begin{pgfonlayer}{background layer} \fill[black] (-.8,-.8) rectangle (.8,.8); \end{pgfonlayer} @@ -122,22 +118,19 @@ the given layer. \fill[blue!50] (-.5,-1) rectangle (.5,1); \end{tikzpicture} \end{codeexample} + % \end{environment} \begin{plainenvironment}{{pgfonlayer}\marg{layer name}} - This is the plain \TeX\ version of the environment. + This is the plain \TeX\ version of the environment. \end{plainenvironment} \begin{contextenvironment}{{pgfonlayer}\marg{layer name}} - This is the Con\TeX t version of the environment. + This is the Con\TeX t version of the environment. \end{contextenvironment} - - - - -%%% Local Variables: +%%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual" -%%% End: +%%% End: |