% ====================================================================== % scrlayer.tex % Copyright (c) Markus Kohm, 2013-2015 % % This file is part of the LaTeX2e KOMA-Script bundle. % % This work may be distributed and/or modified under the conditions of % the LaTeX Project Public License, version 1.3c of the license. % The latest version of this license is in % http://www.latex-project.org/lppl.txt % and version 1.3c or later is part of all distributions of LaTeX % version 2005/12/01 or later and of this work. % % This work has the LPPL maintenance status "author-maintained". % % The Current Maintainer and author of this work is Markus Kohm. % % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlayer.tex % Copyright (c) Markus Kohm, 2013-2015 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. % Die neuste Version dieser Lizenz ist % http://www.latex-project.org/lppl.txt % und Version 1.3c ist Teil aller Verteilungen von LaTeX % Version 2005/12/01 oder spaeter und dieses Werks. % % Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" % (allein durch den Autor verwaltet). % % Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. % % Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. % ====================================================================== % % Chapter about scrlayer of the KOMA-Script guide % Maintained by Markus Kohm % % ---------------------------------------------------------------------- % % Kapitel ueber scrlayer in der KOMA-Script-Anleitung % Verwaltet von Markus Kohm % % ============================================================================ \KOMAProvidesFile{scrlayer.tex} [$Date: 2015-03-31 11:10:59 +0200 (Tue, 31 Mar 2015) $ KOMA-Script guide (chapter:scrlayer)] \translator{Markus Kohm} % Date of the translated file: 2015-03-31 \chapter[{Defining Layers and Page Styles Using \Package{scrlayer}}]% {Defining Layers and Page Styles Using \Package{scrlayer}% } \labelbase{scrlayer} \BeginIndex{Package}{scrlayer}% \BeginIndex{}{layer}% Most users of graphics software already know layer models for pages or working sheets. \LaTeX{} itself does not know layers, but there are already packages like \Package{eso-pic} or \Package{textpos}, that provide a kind of background or foreground layer. \Package{scrlayer} is another package, that provides such background and foreground layers, but in difference to the other packages mentioned above these layers are part of the page style definition. With this you may simply switch between usage of layers by switching the page style. To do so, the package also supports a low level interface to define page styles using a layer stack, to put layers onto a page style's layer stack, to put layers at the lowest position of a page style's layer stack, to put layers before or after a layer of a page style's layer stack, to remove a layer from a page style's layer stack and to remove doublets of layers of a page style's layer stack. In short words: The page style interface of \Package{scrlayer} provides commands to define layer-stack-based page styles and to manage those layer stacks. Nevertheless, using the layers directly is recommended for advanced users only. End user interfaces for beginners or average users are provided by additional packages, that load \Package{scrlayer} on their own. See \autoref{cha:scrlayer-scrpage} in \autoref{part:forAuthors} of this \iffree{manual}{book}. \section{State of Development Note} \seclabel{draft} Development of this package has not been finished yet. Parts of the package are even still experimental. Because of this, especially internal functionality may be changed in future. Most likely the package will be extended. And because of the early state of development, you should not expect a complete and finished user manual. Nevertheless, this manual, which is recommended for advanced users and developers, describes the current state of development and the released parts of \Package{scrlayer}. Everything, not documented here, should not be used for anything else but testing. \LoadCommon{0} % \section{Early or Late Selection of Options} \section{Some Generic Information} \seclabel{generic} The package needs some generic information about the class. Class authors may help \Package{scrlayer} by setting this information. Otherwise the package tries to detect the information itself. This works, e.g., for the standard classes and the \KOMAScript{} classes. But it may or may not fail with other classes. This section describes some of the information, that class authors may provide. Generally users need not to care about this. \begin{Declaration} \Macro{if@chapter}\ \PName{then code} \Macro{else}\ \PName{else code} \Macro{fi}% \end{Declaration} \BeginIndex{Cmd}{if@chapter}% If \Macro{if@chapter} is \Macro{iftrue}, \Package{scrlayer} will additionally consider the chapter level, e.g., processing option \Option{automark}. If it is defined, but differs from \Macro{iftrue}, only part, section, subsection, sub\dots subsection, paragraph, subparagraph, sub\dots subparagraph will be considered. If the macro is not defined, \Package{scrlayer} searches for \Macro{chapter}. If \Macro{chapter} is defined and not \Macro{relax}, \Package{scrlayer} will define \Macro{if@chapter} to \Macro{iftrue}, otherwise \Macro{if@chapter} will become \Macro{iffalse}.% \EndIndex{Cmd}{if@chapter} \begin{Declaration} \Macro{if@mainmatter}\ \PName{then code} \Macro{else}\ \PName{else code} \Macro{fi}% \end{Declaration} \BeginIndex{Cmd}{if@mainmatter}% Classes like \Class{book} define \Macro{frontmatter}, \Macro{mainmatter}, and \Macro{backmatter}. They also use \Macro{if@mainmatter} to distinguish whether or not the current matter is the main matter. Classes like \Class{report} and \Class{article} do not have \Macro{frontmatter}, \Macro{mainmatter}, or \Macro{backmatter} and therefore also do not have \Macro{if@mainmatter}. For \Package{scrlayer} it's easier not to test always for the existence of the matter commands, but to use \Macro{if@mainmatter} even with classes like \Class{report} and \Class{article}, simply set to \Macro{iftrue}. So if \Macro{if@mainmatter} is not defined, it will be defined to \Macro{iftrue}. Some classes have \Macro{frontmatter}, \Macro{mainmatter}, or \Macro{backmatter} but not \Macro{if@mainmatter}. In this case \Package{scrlayer} also defines \Macro{if@mainmatter} to be \Macro{iftrue} and it extends definition of \Macro{frontmatter}, \Macro{mainmatter}, and \Macro{backmatter} to set \Macro{if@mainmatter} properly. Other matter commands are not known, not tested, and not extended. So if there are other matter commands \Package{scrlayer} needs help of the class author to set \Macro{if@mainmatter} correctly.% \EndIndex{Cmd}{if@mainmatter} \begin{Declaration} \Macro{DeclareSectionNumberDepth}%^^A \Parameter{level name}\Parameter{level depth} \end{Declaration} \BeginIndex{Cmd}{DeclareSectionNumberDepth}% Generally each section level is related to an integer number indicating its depth in the document structure. \LaTeX{} needs this to manage hierarchic section levels. But normally only the document class, that defines the section commands, itself knows that \PName{level depth} of a section level and uses these numerical values inside the corresponding commands, when needed. But \Package{scrlayer} also needs information about the section hierarchy. With command \Macro{DeclareSectionNumberDepth} you can map the name of a heading level to a \PName{level depth}. With standard class book, e.g., the \PName{level name} could be \PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, \PValue{subsubsection}, \PValue{paragraph}, or \PValue{subparagraph} and the corresponding \PName{level depth}s would be -1, 0, 1, 2, 3, 4, and 5. Package \Package{scrlayer} tries to determine the \PName{level depth}s on its own while loading and again while \Macro{begin}\PParameter{document}. But, if it fails, i.\,e., if completely different section commands are used, it would be useful, to be able to define the relationship explicitly. For such cases \Macro{DeclareSectionNumberDepth} gives the class author the opportunity to define the relationship explicitly.% \EndIndex{Cmd}{DeclareSectionNumberDepth} \section{Declaration of Layers} \seclabel{layers} A layer is a kind of virtual sheet of transparent paper (in opposite to a physical sheet of paper). One layer is stacked onto another layer and opaque material on one layer may hide material on the layers below. The stack of all layers together makes the physical page. Package \Package{scrlayer} provides two such layer stacks for each page: a background layer stack and a foreground layer stack. The background layer stack is behind the normal page contents, the foreground layer stack is above the normal page contents. So the normal contents is a kind of a separating layer between the background layer stack and the foreground layer stack. A layer has several attributes. The first attribute states, whether or not the layer is part of the foreground or the background. During page building background layers will be printed first, followed by the main contents and the foreground layers. Therefore, in the output the background layers show up behind the main contents and the foreground layers in front of the main contents. By default, a layer is both, a background layer \emph{and} a foreground layer and therefore will be printed twice. The horizontal position of the layer is set by the second attribute, the vertical position by the third. The forth and fifth attributes determine the horizontal and vertical size of the layer. As you can see, a layer may be smaller or larger than the paper. But having two numerical values of the second and third attribute does not directly give us the position of the layer on the page. For each dimension we need two reference points, one on the page and one on the layer. The numerical value than states the distance between these reference. Reference points in layouts are also known as alignment and are set by the sixth attribute. The seventh attribute states, whether or not a layer should be printed onto left or right pages. By default a layer will be printed on both, left and right pages. Note, that \LaTeX{} names left pages as even pages and right pages as odd pages and that there are no left or even pages in single-sided mode. The eighth attribute states, whether or not a layer should be printed in single-side mode or in two-side mode. By default a layer will be printed in both, single-side mode and two-side mode. Nevertheless, an even page layer will never be printed in single-side mode and therefore is not really a two-side mode layer. The ninth attribute is, whether or not a layer should be printed onto float pages or non-float pages. \LaTeX{} produces float pages for float environments like tables or figures, if they are allowed to be printed on a page without normal page contents (see option \PValue{p} for \Environment{figure} or \Environment{table}). So from some point of view a float page is a page, that may itself flow. Non-float pages are not pages without floats, but pages, that are not float pages. They may contain floats inside the text, on the top of the page, or on the bottom of the page. Very large floats may seem to be page floats, while in reality they are top floats. The tenth and last attribute is the contents of the layer. This is simply, what should be printed, whenever the layer will be printed. So we have ten attributes yet. Below in this manual we will describe additional attributes. However, they are just defined for convenience and can be expressed by a combination of the ten attributes stated above. We call these ten attributes the primary attributes. \begin{Declaration} \Macro{DeclareLayer}\OParameter{option list}\Parameter{layer name}\\ \Macro{DeclareNewLayer}\OParameter{option list}\Parameter{layer name}\\ \Macro{ProvideLayer}\OParameter{option list}\Parameter{layer name}\\ \Macro{RedeclareLayer}\OParameter{option list}\Parameter{layer name}\\ \Macro{ModifyLayer}\OParameter{option list}\Parameter{layer name} \end{Declaration} \BeginIndex{Cmd}{DeclareLayer}% \BeginIndex{Cmd}{DeclareNewLayer}% \BeginIndex{Cmd}{ProvideLayer}% \BeginIndex{Cmd}{RedeclareLayer}% \BeginIndex{Cmd}{ModifyLayer}% These commands can be used to define a layer. The \PName{layer name} has to be fully expandable and should expand to letters only. Some additional characters are tolerated, but are not recommended. Command \Macro{DeclareLayer} does not care whether or not a layer with the given \PName{layer name} already exists. It will under all circumstances define the layer with the attribute defined by the \PName{option list}. An \PName{option} can be either a key or a key followed by an equal sign followed by a value. Several options may be concatenated to a \PName{option list} and have to be separated by comma. If you'd like to have a comma or a white space inside the value of an option, you should put the value inside curly brackets. See \autoref{tab:scrlayer.layerkeys} for more information on keys, values, and the corresponding attributes. In contrast to \Macro{DeclareLayer} using \Macro{DeclareNewLayer} results in an error, if a layer with the same \PName{layer name} already exists. So you may prevent yourself using the same \PName{layer name} more than once by mistake. This would be useful, e.\,g., if a class or package also defines layers internally. If you use \Macro{ProvideLayer} instead of \Macro{DeclareLayer}, the declaration will be ignored in case a layer with the same layer name already exists. It could be paraphrased by: \emph{declare the layer only if it has not been declared already.} If an existing layer should be redefined, \Macro{RedeclareLayer} or \Macro{ModifyLayer} can be used. \Macro{RedeclareLayer} would simply define the layer as if it would be defined newly. In difference to this, \Macro{ModifyLayer} would change only those attributes, that are represented by an option of the \PName{option list}. All other attributes will stay unchanged and will not be reset to the initial default value. Using either \Macro{RedeclareLayer} or \Macro{ModifyLayer} will result in an error, in case there has not been a layer with \PName{layer name} defined before. \begin{desclist} \desccaption{% Options for the definition of page layers with description of the corresponding layer attribute\label{tab:scrlayer.layerkeys}% }{% Options for the definition of layers (\emph{Continuation})% }% \ifnum\currentversionlt{3.16}\else \nentry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \KOption{addcontents}\PName{Code}}{% Value \PName{code} will be added (or appended) at the very end of the current value of attribute \Option{contents}. So the new content will be generated behind the end of the already existing content. For more information about the handling of \PName{code} see option \Option{contents}.% }% \nentry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \KOption{addheight}\PName{additional height}}{% The current value of attribute \Option{height} will be increased by the value of this option. You can use the same kind of values as for \Option{height}.% }% \nentry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \KOption{addhoffset}\PName{additional horizontal offset}}{% The current value of attribute \Option{hoffset} will be increased by the value of this option. You can use the same kind of values as for \Option{hoffset}.% }% \nentry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \KOption{addvoffset}\PName{additional vertical offset}}{% The current value of attribute \Option{voffset} will be increased by the value of this option. You can use the same kind of values as for \Option{voffset}.% }% \nentry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \KOption{addwidth}\PName{additional width}}{% The current value of attribute \Option{width} will be increased by the value of this option. You can use the same kind of values as for \Option{width}.% }% \fi \nentry{\KOption{align}{\PName{alignment characters}}}{% The \PName{alignment characters} define the desired alignment of the layer. Each \PName{alignment character} influences either, how argument \PName{length} of option \Option{hoffset} or \Option{voffset} will be used. Several \PName{alignment characters} may be used together (without comma or space) and will be interpreted in the order of occurrence. No macros should be used here! Valid \PName{alignment character}s are: \begin{description} \item[\PValue{b} --] align the layer at its bottom edge; the value of \Option{voffset} is interpreted as the distance from the top edge of the paper to the bottom edge of the layer. \item[\PValue{c} --] align the layer at its centre; the values of \Option{voffset} and \Option{hoffset} are interpreted as the distance from the top left corner of the paper to the centre of the layer. \item[\PValue{l} --] align the layer at its left edge: the value of \Option{hoffset} is interpreted as the distance from the left edge of the paper to the left edge of the layer. \item[\PValue{r} --] align the layer at its right edge; the value of \Option{hoffset} is interpreted as the distance from the left edge of the paper to the right edge of the layer. \item[\PValue{t} --] align the layer at its top edge; the value of \Option{voffset} is interpreted as the distance from the top edge of the paper to the top edge of the layer. \end{description}% }% \nentry{\KOption{area}{%^^A \Parameter{hoffset}\Parameter{voffset}%^^A \Parameter{width}\Parameter{height}}}{% The composed option results in \OptionValue{hoffset}{\PName{hoffset}}, \OptionValue{voffset}{\PName{voffset}}, \OptionValue{width}{\PName{width}}, \OptionValue{height}{\PName{height}}.% }% \entry{\Option{background}}{% Print the layer only in the background, but not in the foreground. This makes a background-only layer in opposite to the default of layers which are both, background and foreground layers and therefore would be printed twice. The option does not expect any value. By the default the attribute is not set.% }% \entry{\Option{bottommargin}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally span the paper from the left edge to the right and vertically span the area below the footer down to the bottom edge of the paper.% }% \nentry{\KOption{clone}{\PName{layer name}}}{% The composed option sets all primary attributes of the layer to the same values as the primary attributes of the layer with the given \PName{layer name}. Note, that \PName{layer name} has to be fully expandable and should expand to letters only. Some additional characters are tolerated, but are not recommended!% }% \nentry{\KOption{contents}{\PName{code}}}{% The \PName{code} will be expanded whenever the layer is printed. So the \PName{code} is what you will see. Code validity is not checked. So errors in \PName{code} may result in several failures on each page, that prints the layer.% }% \entry{\Option{evenpage}}{% Print the layer on even pages only, but not on odd pages. The option does not expect any value. By the default the option is not set and therefore layers would be printed on odd pages and on even pages. Note, that this attribute subsumes \Option{twoside}.% }% \entry{\Option{floatpage}}{% Print the layer on float pages only, but not on other pages. The option does not expect any value. By the default the attribute is not set and therefore layers would be printed on float pages and on non-float pages.% }% \entry{\Option{foot}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally span the text area and vertically span the page footer defined by the new \LaTeX{} length \Length{footheight}.% }% \entry{\Option{footskip}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally span the text area and vertically span the distance between the text area and the page footer (note, that this is not the same like \Length{footskip}).% }% \entry{\Option{foreground}}{% Print the layer only in the foreground, but not in the background. This makes a foreground-only layer in opposite to the default of layers which are both, background and foreground layers and therefore would be printed twice. The option does not expect any value. By the default the attribute is not set.% }% \entry{\Option{head}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally span the text area and vertically span the page head defined by usual \LaTeX{} length \Length{headheight}.% }% \entry{\Option{headsep}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally span the text area and vertically span the distance between the page head and the text area.% }% \nentry{\KOption{height}{\PName{length}}}{% Sets the height of the layer. Note, that \PName{length} can either be a \LaTeX{} length, declared using \Macro{newlength}, or a \TeX{} length, declared using \Macro{newdimen} or \Macro{newskip}, a length value like 10\,pt, or a dimensional expression using +, -, /, *, (, and ). For more information about valid dimensional expressions see \cite[section~3.5]{manual:eTeX}.% }% \nentry{\KOption{hoffset}{\PName{length}}}{% Sets the offset of the layer (depending on \Option{align} either left edge of the layer, middle of the layer or right edge of the layer) from the left edge of the paper. See \Option{height} for more information about valid content of \PName{length}.% }% \entry{\Option{innermargin}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally span the distance between the right edge of text area and the right edge of the paper on even pages or the distance between the left edge of the paper and the left edge of the text area on odd pages and vertically span the whole paper from the top edge to the bottom edge.% }% \entry{\Option{leftmargin}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally span the distance between the left edge of the paper and the left edge of the text area and vertically span the whole paper from the top edge to the bottom edge.% }% \entry{\Option{nonfloatpage}}{% Restricts the layer to pages, that are not float pages. The option does not expect any value. By the default the attribute is not set and therefore layers would be printed on float pages and on non-float pages.% }% \entry{\Option{oddpage}}{% Print the layer on odd pages only, but not on even pages. The option does not expect any value. By the default the option is not set and therefore layers would be printed on odd pages and on even pages.% }% \entry{\Option{oneside}}{% Print the layer in single-side mode only, but not in two-side mode. The option does not expect any value. By the default the attribute is not set and therefore layers would be printed in single-side and two-side mode.% }% \entry{\Option{outermargin}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally span the distance between the left edge of the paper and the left edge of the text area on even pages or the distance between the right edge of the text area and the right edge of the paper on odd pages and vertically span the whole paper from the top edge to the bottom edge.% }% \entry{\Option{page}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally and vertically span the whole paper from the left edge to the right edge and the top edge to the bottom edge.% }% \ifnum\currentversionlt{3.16}\else \nentry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \KOption{pretocontents}\PName{code}}{% Value \PName{code} will be added at the very beginning of the current value of attribute \Option{contents}. So the new content will be generated in front of the already existing content. For more information about the handling of \PName{code} see option \Option{contents}.% }% \fi \entry{\Option{rightmargin}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally span the distance between the right edge of text area and the right edge of the paper and vertically span the whole paper from the top edge to the bottom edge.% }% \entry{\Option{textarea}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally and vertically span the whole text area from the left edge to the right edge and the top edge to the bottom edge.% }% \entry{\Option{topmargin}}{% The composed option sets \Option{hoffset}, \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} to horizontally span the whole page from the left edge to the right edge and vertically span the distance between the top edge of the paper and the page head.% }% \entry{\Option{twoside}}{% Print the layer in two-side mode only, but not in single-side mode. The option does not expect any value. By the default the attribute is not set and therefore layers would be printed in single-side and two-side mode.% }% \nentry{\KOption{voffset}{\PName{length}}}{% Sets the offset of the layer (depending on \Option{align} either top edge of the layer, middle of the layer or bottom edge of the layer) from the top edge of the paper. See \Option{height} for more information about valid content of \PName{length}.% }% \nentry{\KOption{width}{\PName{length}}}{% Sets the width of the layer. See \Option{height} for more information about valid content of \PName{length}.% }% \end{desclist} % \EndIndex{Cmd}{ModifyLayer}% \EndIndex{Cmd}{RedeclareLayer}% \EndIndex{Cmd}{ProvideLayer}% \EndIndex{Cmd}{DeclareNewLayer}% \EndIndex{Cmd}{DeclareLayer}% \begin{Declaration} \Macro{layerxoffset}\\ \Macro{layeryoffset}\\ \Macro{layerwidth}\\ \Macro{layerheight}% \end{Declaration} \BeginIndex{Cmd}{layerxoffset}% \BeginIndex{Cmd}{layeryoffset}% \BeginIndex{Cmd}{layerwidth}% \BeginIndex{Cmd}{layerheight}% These commands are valid during output of the layer's contents only. So they can only be used inside the \PName{code} of option \Option{contents} of the previously described commands. In this case they give the effective position and dimension of the layer, that will be used for the output. However, the effective dimension of the layer's contents may differ, i.\,e., if the contents are oversized or do not fill the layer completely. Redefinition of the commands to change the stored values is strictly forbidden and would result in unpredictable issues.% \EndIndex{Cmd}{layerheight}% \EndIndex{Cmd}{layerwidth}% \EndIndex{Cmd}{layeryoffset}% \EndIndex{Cmd}{layerxoffset}% \ifnum\currentversionlt{3.16}\else \begin{Declaration} \Macro{GetLayerContents}\Parameter{layer name} \end{Declaration} \BeginIndex{Cmd}{GetLayerContents}% This\ChangedAt{v3.16}{\Package{scrlayer}} command results in the whole content of a layer. You have to note\textnote{Attention!} that using this command inside the \PName{code} of the layer attributes \Option{contents}, \Option{addcontents}, or \Option{pretocontents} can result in an infinite recursion, if the content of the current layer is referenced. You yourself should avoid such situations!% \EndIndex{Cmd}{GetLayerContents}% \fi \begin{Declaration} \Macro{IfLayerExists}% \Parameter{string}\Parameter{then-code}\Parameter{else-code} \end{Declaration} \BeginIndex{Cmd}{IfLayerExists}% This command may be used to execute code depending on whether or not a layer has been defined already. If the layer exists \PName{then-code} will be executed, otherwise \PName{else-code}. Note, the command cannot really test whether a layer exists. It uses a heuristic, that will never be false negative, but may be false positive. Nevertheless, if it is false positive something went wrong, either an incompatible package has been used or the user made something he should not do.% \EndIndex{Cmd}{IfLayerExists} \begin{Declaration} \Macro{DestroyLayer}\Parameter{layer name} \end{Declaration} \BeginIndex{Cmd}{DestroyLayer}% This command sets all macros corresponding with the layer with given \PName{layer name} to \Macro{relax}, if a layer with that name exists. As a result the layer cannot be used any longer. It does not matter, if the layer is still part of the layer list of a page style, because such destroyed layers will be ignored. Nevertheless, destroyed layers may be defined again using \Macro{DeclareNewLayer} or \Macro{ProvideLayer}, but cannot be changed using \Macro{RedeclareLayer} or \Macro{ModifyLayer} any longer. The command is intended to be used inside \Macro{scrlayerOnAutoRemoveInterface} to remove layers, which have been defined using removable macros of an interface, whenever the interface would be removed.% \EndIndex{Cmd}{DestroyLayer} \begin{Declaration} \Macro{layercontentsmeasure}% \end{Declaration} \BeginIndex{Cmd}{layercontentsmeasure}% The command \Macro{layercontentsmeasure} prints a ruler at each layer edge, of which the top and left one is labelled with centimeters, the right and bottom one with inches. This command is used internally, if option \Option{draft}\IndexOption{draft} is enabled. The rulers will be drawn behind the content of each layer. It can also be used as exclusive content of a layer.% \EndIndex{Cmd}{layercontentsmeasure} \section{Declaration and Management of Page Styles} \seclabel{pagestyles} Until now we know layers, but we do not know how to use them. The perhaps astonishing answer is: with page styles. In \LaTeX{}, page styles usually define heads and foots of odd and even pages. The head and foot of odd pages will be printed on pages with odd page number in two-side mode or on all pages in single-side mode. This is something like the layer attributes \Option{oddpage} and \Option{evenpage}. The page head will be printed before the main contents of a page. The page footer will be printed after the main contents of a page. So this is something like the layer attributes \Option{background} and \Option{foreground}. So it suggests itself to declare page styles as a list of layers. But instead of having only four attributes \Option{oddpage}, \Option{evenpage}, \Option{background}, and \Option{foreground} all the attributes of layers shown in \autoref{sec:scrlayer.layers} may be used. The outcome of all such considerations is that layer page styles are one type of page styles \Package{scrlayer} provides. A layer page style consists of layers and several \emph{hooks}. For description of layers see \autoref{sec:scrlayer.layers}. The \emph{hooks} are points in the expansion or execution of page styles you may add additional code to. Advanced users know this already from commands like \Macro{AtBeginDocument} (see \cite{latex:usrguide}) or \Macro{BeforeClosingMainAux} (see \autopageref{desc:scrlfile.cmd.BeforeClosingMainAux}). Alias page styles are another type of page styles provided by \Package{scrlayer}. An alias page style wraps another page style. In other words, the name of an alias page style is an alias name of another page style, the aliased or original page style. Because of this, the manipulation of an alias page style results in the manipulation of the original page style. If the original page style is an alias page style too, the manipulation will result in the manipulation of the aliased page style of that original page style and so on until a real page style will be manipulated. Aliasing is not restricted to \Package{scrlayer} page styles, but possible for all page styles. \begin{Declaration} \Macro{currentpagestyle} \end{Declaration} \BeginIndex{Cmd}{currentpagestyle}% Package scrlayer patches \Macro{pagestyle} to set \Macro{currentpagestyle} to the currently active page style. Note, \Macro{thispagestyle} does not change \Macro{currentpagestyle}. But if you use \Macro{thispagestyle} the result of \Macro{currentpagestyle} may be changed while executing the \LaTeX{} output routine. However, this change will only occur, if \Macro{currentpagestyle} has been actively protected from expansion up to execution of the output routine. Note, the layer page styles described later in this section, will not need the patch of \Macro{pagestyle} to set \Macro{currentpagestyle}. The patch has been made for usage with other page styles. Additionally, \Macro{currentpagestyle} is empty before the first \Macro{pagestyle} after loading \Package{scrlayer}. So if you define an end user page style interface, it may be useful to use an implicit \Macro{pagestyle} to set the current page style to a default page style.% \EndIndex{Cmd}{currentpagestyle} \begin{Declaration} \Macro{BeforeSelectAnyPageStyle}\Parameter{code}\\ \Macro{AfterSelectAnyPageStyle}\Parameter{code}%^^A \end{Declaration} \BeginIndex{Cmd}{BeforeSelectAnyPageStyle}% \BeginIndex{Cmd}{AfterSelectAnyPageStyle}% The command \Macro{BeforeSelectAnyPageStyle} adds \PName{code} to the hook that will be executed inside of \Macro{pagestyle} just before the page style will be selected. You may use \texttt{\#1} as a placeholder for the argument of \Macro{pagestyle}. The command \Macro{AfterSelectAnyPageStyle} is similar, but the \PName{code} will be executed just after the page style has been selected and after \Macro{currentpagestyle} has been set to the name of the real page style. Note\textnote{Attention!}, \PName{code} of both commands will be executed only if a page style will be selected using \Macro{pagestyle}, but not, e.\,g., if a page style will be selected using \Macro{thispagestyle}. Note also, you cannot remove \PName{code} from the hook after adding it. But the \PName{code} will be added locally, so you may use a group to limit the scope of \PName{code}.%^^A \EndIndex{Cmd}{AfterSelectAnyPageStyle} \EndIndex{Cmd}{BeforeSelectAnyPageStyle} \begin{Declaration} \Macro{DeclarePageStyleAlias}% \Parameter{alias page style name}\Parameter{original page style name}\\ \Macro{DeclareNewPageStyleAlias}% \Parameter{alias page style name}\Parameter{original page style name}\\ \Macro{ProvidePageStyleAlias}% \Parameter{alias page style name}\Parameter{original page style name}\\ \Macro{RedeclarePageStyleAlias}% \Parameter{alias page style name}\Parameter{original page style name} \end{Declaration} \BeginIndex{Cmd}{DeclarePageStyleAlias}% \BeginIndex{Cmd}{DeclareNewPageStyleAlias}% \BeginIndex{Cmd}{ProvidePageStyleAlias}% \BeginIndex{Cmd}{RedeclarePageStyleAlias}% These commands may be used to define a page style with name \PName{alias page style name} that is simply an alias for an already existing page style with name \PName{original page style name}. If there is already a page style \PName{alias page style name}, then using \Macro{DeclarePageStyleAlias} or \Macro{RedeclarePageStyleAlias} will destroy the alias before recreating it. \Macro{DeclareNewPageStyleAlias} will throw an error message, if a page style \PName{alias page style name} has already been defined before. It does not matter if the already defined page style is a layer page style, an alias page style or another page style. \Macro{ProvidePageStyleAlias} will define the alias only if a page style \PName{alias page style name} has not been defined before. If a page style \PName{alias page style name} already exists nothing will be done. \Macro{RedeclarePageStyleAlias} expects an already existing page style \PName{alias page style name}. It will destroy that page style and afterwards define the alias. If the page style \PName{alias page style name} does not exist, then you will get an error.% \EndIndex{Cmd}{RedeclarePageStyleAlias}% \EndIndex{Cmd}{ProvidePageStyleAlias}% \EndIndex{Cmd}{DeclareNewPageStyleAlias}% \EndIndex{Cmd}{DeclarePageStyleAlias} \begin{Declaration} \Macro{DestroyPageStyleAlias}\Parameter{page style name}% \end{Declaration} \BeginIndex{Cmd}{DestroyPageStyleAlias}% This command makes the page style with given \PName{page style name} \LaTeX-undefined, if it is an alias for another page style. Afterwards, the page style may be defined newly with, e.g., \Macro{DeclareNewAliasPageStyle} or \Macro{ProvideAliasPageStyle}. The command is intended to be used inside of \Macro{scrlayerOnAutoRemoveInterface} to remove page styles that have been declared by an interface and use removable macros of that interface.% \EndIndex{Cmd}{DestroyPageStyleAlias} \begin{Declaration} \Macro{GetRealPageStyle}\Parameter{page style name}% \end{Declaration} \BeginIndex{Cmd}{GetRealPageStyle}% The command will result in the (recursive) real page name of the page style, if the page style with given name \PName{page style name} is an alias of another page style. In all other cases, even if there's no alias and no page style named \PName{page style name}, the result would be simply \PName{page style name}. The command is fully expandable and may be used, e.g., in the second argument of \Macro{edef}.% \EndIndex{Cmd}{GetRealPageStyle} \begin{Declaration} \Macro{DeclarePageStyleByLayers}% \OParameter{option list}\Parameter{page style name}\Parameter{layer list}\\ \Macro{DeclareNewPageStyleByLayers}% \OParameter{option list}\Parameter{page style name}\Parameter{layer list}\\ \Macro{ProvidePageStyleByLayers}% \OParameter{option list}\Parameter{page style name}\Parameter{layer list}\\ \Macro{RedeclarePageStyleByLayers}%^ \OParameter{option list}\Parameter{page style name}\Parameter{layer list}% \end{Declaration} \BeginIndex{Cmd}{DeclarePageStyleByLayers}% \BeginIndex{Cmd}{DeclareNewPageStyleByLayers}% \BeginIndex{Cmd}{ProvidePageStyleByLayers}% \BeginIndex{Cmd}{RedeclarePageStyleByLayers}% These commands declare a page style with \PName{page style name}. The page style will consist of the layers given in \PName{layer list}, a comma separated list of layer names. Note, the \PName{page style name} and the layer names at the \PName{layer list} must be fully expandable and should expand to letters. Several other characters are tolerated, but, nevertheless, not recommended. The \PName{option list} is a comma separated list of \OptionValue{\PName{key}}{\PName{value}} options. These options may be used to set additional features. Currently they are used to set the code that should be expanded or executed at several \emph{hooks}. See the introduction to this section for more general information about \emph{hooks}. See \autoref{tab:scrlayer.pagestyle.hooks} for detailed information on specific hooks. \begin{desclist} \desccaption{% The \emph{hook} options for page styles (in order of execution)\label{tab:scrlayer.pagestyle.hooks}% }{% The \emph{hook} options for page styles (\emph{Continuation})% }% \entry{\KOption{onselect}\PName{code}}{% Execute \PName{code} whenever the page style is selected using, e.g., \Macro{pagestyle}. Note\textnote{Attention!}, \Macro{thispagestyle} does not select the page style immediately, but asynchronously inside \LaTeX's output routine.% }% \entry{\KOption{oninit}\PName{code}}{% Execute \PName{code} whenever the output of page style's layers is initialised. Note\textnote{Attention!}, this is done twice for every page: once for background layers and once for foreground layers.% }% \entry{\KOption{ononeside}\PName{code}}{% Execute \PName{code} whenever the output of page style's layers in single-side mode is initialised. Note\textnote{Attention!}, this is done twice for every page: once for background layers and once for foreground layers.% }% \entry{\KOption{ontwoside}\PName{code}}{% Execute \PName{code} whenever the output of page style's layers in two-side mode is initialised. Note\textnote{Attention!}, this is done twice for every page: once for background layers and once for foreground layers.% }% \entry{\KOption{onoddpage}\PName{code}}{% Execute \PName{code} whenever the output of page style's layers on an odd page is initialised. Note\textnote{Attention!}, this is done twice for every page: once for background layers and once for foreground layers. Note\textnote{Attention!} also that in single-side mode all pages are odd pages, not only pages with odd page numbers.% }% \entry{\KOption{onevenpage}\PName{code}}{% Execute \PName{code} whenever the output of page style's layers on an even page is initialised. Note\textnote{Attention!}, this is done twice for every page: once for background layers and once for foreground layers. Note\textnote{Attention!} also that there are not even pages in single-side mode, but all pages are odd pages, not only pages with odd page numbers.% }% \entry{\KOption{onfloatpage}\PName{code}}{% Execute \PName{code} whenever the output of page style's layers on a float page are initialised. Note\textnote{Attention!}, this is be done twice for every page: once for background layers and once for foreground layers. Note\textnote{Attention!} also that float pages are only those pages with p-placed floating objects.% }% \entry{\KOption{onnonfloatpage}\PName{code}}{% Execute \PName{code} whenever the output of page style's layers on a non-float page is initialised. Note\textnote{Attention!}, this is done twice for every page: once for background layers and once for foreground layers. Note\textnote{Attention!} also that non-float pages are all pages that are not float-pages. Those pages may have t-placed, h-placed, b-placed, or no floating objects.% }% \entry{\KOption{onbackground}\PName{code}}{% Execute \PName{code} whenever the output of page style's layers in the background of a page is initialised. Note\textnote{Attention!}, this is done once for every page.% }% \entry{\KOption{onforeground}\PName{code}}{% Execute \PName{code} whenever the output page style's layers in the foreground of a page is initialised. Note\textnote{Attention!}, this is done once for every page.% }% \end{desclist} The difference of \Macro{DeclarePageStyleByLayers} and \Macro{DeclareNewPageStyleByLayers} is that \Macro{DeclareNewPageStyleByLayers} will result in an error, if a page style with name \PName{page style name} already exists. Note, declaring a page style, which is an alias of another page style (see \Macro{DeclareAliasPageStyle} prior in this section), will not re-declare the page style itself, but it's real page style (see \Macro{GetRealPageStyle} prior in this section). The difference of \Macro{DeclarePageStyleByLayers} and \Macro{ProvidePageStyleByLayers} is that \Macro{ProvidePageStyleByLayers} will simply do nothing, if there's already a page style with name \PName{page style name}. In difference to \Macro{DeclareNewPageStyleByLayers} it will not raise an error. The difference of \Macro{DeclarePageStyleByLayers} and \Macro{RedeclarePageStyleByLayers} is, that \Macro{RedeclarePageStyleByLayers} may be used only if the real page style of \PName{page style name} already exists. Otherwise an error occurs. Please have also a look at the notes to following pseudo page style \Pagestyle{@everystyle@}.% \EndIndex{Cmd}{RedeclarePageStyleByLayers}% \EndIndex{Cmd}{ProvidePageStyleByLayers}% \EndIndex{Cmd}{DeclareNewPageStyleByLayers}% \EndIndex{Cmd}{DeclarePageStyleByLayers}% \begin{Declaration} \Pagestyle{@everystyle@}\\ \Pagestyle{empty} \end{Declaration} \BeginIndex{Pagestyle}{@everysel@}% \BeginIndex{Pagestyle}{empty}% There are two default layer page styles that are somehow special. The first one is \Pagestyle{@everystyle@}. This page style should not be used like any other page style, but the layers of this page style will be used by all the other layer page styles. So adding a layer to this page style is similar to adding this layer to all other layer page styles even the empty one. There's one difference: Layer referencing commands of the page style interface like \Macro{ForEachLayerOfPageStyle}, \Macro{AddLayerToPageStyleBeforeLayer}, or \Macro{AddLayerToPageStyleAfterLayer} process only the layers of the page style that has been referenced but not the layers implicated by \Pagestyle{@everystyle@}. The other somehow special page style is \Pagestyle{empty}. Normally page style \Pagestyle{empty} is defined by the \LaTeX{} kernel, to be a page style without page head or page foot. Package \Package{scrlayer} re-defines it to be a layer page style without any layer. Nevertheless, you may use it like every other layer page style too. The main advantage above the \LaTeX{} kernel's empty page style is that it also executes the layers of special layer page style \Pagestyle{@everysel@}.% \EndIndex{Pagestyle}{empty}% \EndIndex{Pagestyle}{@everysel@}% \begin{Declaration} \KOption{onpsselect}\PValue{code}\\ \KOption{onpsinit}\PValue{code}\\ \KOption{onpsoneside}\PValue{code}\\ \KOption{onpstwoside}\PValue{code}\\ \KOption{onpsoddpage}\PValue{code}\\ \KOption{onpsevenpage}\PValue{code}\\ \KOption{onpsfloatpage}\PValue{code}\\ \KOption{onpsnonfloatpage}\PValue{code}\\ \KOption{onpsbackground}\PValue{code}\\ \KOption{onpsforeground}\PValue{code} \end{Declaration} \BeginIndex{Option}{onpsselect~=\PName{code}}% \BeginIndex{Option}{onpsinit~=\PName{code}}% \BeginIndex{Option}{onpsoneside~=\PName{code}}% \BeginIndex{Option}{onpstwoside~=\PName{code}}% \BeginIndex{Option}{onpsoddpage~=\PName{code}}% \BeginIndex{Option}{onpsevenpage~=\PName{code}}% \BeginIndex{Option}{onpsfloatpage~=\PName{code}}% \BeginIndex{Option}{onpsnonfloatpage~=\PName{code}}% \BeginIndex{Option}{onpsbackground~=\PName{code}}% \BeginIndex{Option}{onpsforeground~=\PName{code}}% There's also a \KOMAScript{} option for each of those \texttt{hooks}. The names of the \KOMAScript{} options are similar to the names of the page style options, but with ``\texttt{ps}'' inserted behind ``\texttt{on}''. The value of the \KOMAScript{} options are the initial defaults of the corresponding \texttt{hooks}. These defaults will be extended at every declaration of page style hook options via \PName{option list}. You may remove the default, using \Macro{ModifyLayerPageStyleOptions} described later in this section.% \EndIndex{Option}{onpsforeground~=\PName{code}}% \EndIndex{Option}{onpsbackground~=\PName{code}}% \EndIndex{Option}{onpsnonfloatpage~=\PName{code}}% \EndIndex{Option}{onpsfloatpage~=\PName{code}}% \EndIndex{Option}{onpsevenpage~=\PName{code}}% \EndIndex{Option}{onpsoddpage~=\PName{code}}% \EndIndex{Option}{onpstwoside~=\PName{code}}% \EndIndex{Option}{onpsoneside~=\PName{code}}% \EndIndex{Option}{onpsinit~=\PName{code}}% \EndIndex{Option}{onpsselect~=\PName{code}}% \begin{Declaration} \KOption{deactivatepagestylelayers}\PName{simple switch}\\ \Macro{ForEachLayerOfPageStyle}\Parameter{page style name}\Parameter{code} \end{Declaration} \BeginIndex{Cmd}{ForEachLayerOfPageStyle}% As long as \KOMAScript{} option \Option{deactivatepagestylelayers} has not been activated command \Macro{ForEachLayerOfPageStyle} can be used to process \PName{code} for every member layer of \PName{page style name}'s layers list. Inside of \PName{code} the place holder \PValue{\#1} may be used to reference the name of the current layer. \begin{Example} If you want to print the names of all layers of page style \PValue{scrheadings}, you may us: \begin{lstcode} \let\commaatlist\empty \ForEachLayerOfPageStyle{scrheadings}{% \commaatlist#1\gdef\commaatlist{, }} \end{lstcode} \end{Example} Usage of \Macro{gdef} instead of \Macro{def} is necessary in the example above, because \Macro{ForEachLayerOfPageStyle} executes the \PName{code} inside of a group to minimise side effects. Here \Macro{gdef} redefines \Macro{commaatlist} globally, so it would be still valid at the execution of \PName{code} for the next layer. Several other commands of \Package{scrlayer} also use \Macro{ForEachLayerOfPageStyle} internally. So these also do not process any layer if \KOMAScript{} option \Option{deactivatepagestylelayers} would be activated. So you may use this options, e.g., to hide all layers of all layer page styles.% \EndIndex{Cmd}{ForEachLayerOfPageStyle}% \begin{Declaration} \Macro{AddLayersToPageStyle}% \Parameter{page style name}\Parameter{layer list}\\ \Macro{AddLayersAtBeginOfPageStyle}% \Parameter{page style name}\Parameter{layer list}\\ \Macro{AddLayersAtEndOfPageStyle}% \Parameter{page style name}\Parameter{layer list}\\ \Macro{RemoveLayersFromPageStyle}% \Parameter{page style name}\Parameter{layer list}% \end{Declaration} \BeginIndex{Cmd}{AddLayersToPageStyle}% \BeginIndex{Cmd}{AddLayersAtBeginOfPageStyle}% \BeginIndex{Cmd}{AddLayersAtEndOfPageStyle}% \BeginIndex{Cmd}{RemoveLayersFromPageStyle}% You can use these commands to add layers to a layer page style or to remove layers from a layer page style. The page style will be referenced by \PName{page style name}. The layers are given by a comma separated \PName{layer list}. The commands \Macro{AddLayersToPageStyle} and \Macro{AddLayersAtEndOfPageStyle} add all layers of the comma separated list of layers \PName{layer list} at the end of the layer list of layer page style \PName{page style name}. Logically the added layers would be above or in front of the old layers of the page style. Nevertheless, new background layers would be behind the text layer and therefore behind all foreground layers. Command \Macro{AddLayersAtBeginOfPageStyle} adds the new layers at the begin of the layer list of the page style. Note, the layers will be added in the order of the \PName{layer list}. The first layer at \PName{layer list} will be added first, the second layer will be added second and so on. So with \Macro{AddLayersAtBeginOfPageStyle} the last layer at \PName{layer list} will become the new first layer of the layer list of layer page style \PName{page style name}. Command \Macro{RemoveLayersFromPageStyle} may be used to remove layers from the layer list of layer page style \PName{page style name} instead of adding them. Note, layers, which are part of \PName{layer list}, but not part of the page style's layer list, will be ignored. But adding or removing layers from a page style, which is not a layer page style or an alias of a layer page style, would be a mistake and result in an error message.% \EndIndex{Cmd}{RemoveLayersFromPageStyle}% \EndIndex{Cmd}{AddLayersAtEndOfPageStyle}% \EndIndex{Cmd}{AddLayersAtBeginOfPageStyle}% \EndIndex{Cmd}{AddLayersToPageStyle} \begin{Declaration} \Macro{AddLayersToPageStyleBeforeLayer}% \Parameter{page style name}\Parameter{layer list}% \Parameter{reference layer name}\\ \Macro{AddLayersToPageStyleAfterLayer}% \Parameter{page style name}\Parameter{layer list}% \Parameter{reference layer name} \end{Declaration} \BeginIndex{Cmd}{AddLayersToPageStyleBeforeLayer}% \BeginIndex{Cmd}{AddLayersToPageStyleAfterLayer}% These commands are similar to the commands described before, but they do not add the layers at the begin or end of the layer list of a layer page style, but just before or after a reference layer at the layer list of a layer page style. Note, in this case the order of the \PName{layer list} will be same in the layer list of \PName{page style name} after adding. If the reference layer named \PName{reference layer name} is not part of the layer list of the layer page style, nothing happens.% \EndIndex{Cmd}{AddLayersToPageStyleAfterLayer}% \EndIndex{Cmd}{AddLayersToPageStyleBeforeLayer} \begin{Declaration} \Macro{UnifyLayersAtPageStyle}\Parameter{page style name} \end{Declaration} \BeginIndex{Cmd}{UnifyLayersAtPageStyle}% With the commands described before in this section you may not only add different layers to a page style, but even add the same layer several times to a page style. In most cases it does not make sense to have one layer several times at the layer list of a layer page style. So you may use \Macro{UnifyLayersAtPageStyle} to remove all dupes of layers from the layer list of a layer page style. Note\textnote{Attention!}, the order of layers may change! So if you want a special order, you should remove all layers and add the layers in the order you want instead of using \Macro{UnifyLayersAtPageStyle}.% \EndIndex{Cmd}{UnifyLayersAtPageStyle} \begin{Declaration} \Macro{ModifyLayerPageStyleOptions}% \Parameter{page style name}\Parameter{option list}\\ \Macro{AddToLayerPageStyleOptions}% \Parameter{page style name}\Parameter{option list} \end{Declaration} \BeginIndex{Cmd}{ModifyLayerPageStyleOptions}% \BeginIndex{Cmd}{AddToLayerPageStyleOptions}% Command \Macro{ModifyLayerPageStyleOptions} may be used to modify the page style options of a layer page style. Only options at the comma separated \PName{option list} will be set to the new values given in \PName{option list} if the new value is not empty. Options, which are not at \PName{option list}, will stay unchanged. If you want to set an option to \emph{do nothing} you may use value \Macro{relax}. Note, setting an option to a new value using \Macro{ModifyLayerPageStyleOptions} will remove the previous value including the global default value. \Macro{AddToLayerPageStyleOptions} differs from \Macro{ModifyLayerPageStyleOptions} in that point. It will not overwrite the previous values, but adds\,---\,or more precisely: concatenates\,---\, the new values to the previous values of the options at \PName{option list}.% \EndIndex{Cmd}{AddToLayerPageStyleOptions}% \EndIndex{Cmd}{ModifyLayerPageStyleOptions}% \begin{Declaration} \Macro{IfLayerPageStyleExists}% \Parameter{page style name}\Parameter{then code}\Parameter{else code}\\ \Macro{IfRealLayerPageStyleExists}%^ \Parameter{page style name}\Parameter{then code}\Parameter{else code}% \end{Declaration} \BeginIndex{Cmd}{IfLayerPageStyleExists}% \BeginIndex{Cmd}{IfRealLayerPageStyleExists}% Command \Macro{IfLayerPageStyleExists} tests, whether or not the real page style of \PName{page style name} is a layer page style. If the test is true, \PName{then code} will be executed. If \PName{page style name} is neither a layer page style, nor an alias of a layer page style, nor an alias of an alias of \dots\ a layer page style, \PName{else code} will be executed. Internally this command is often used to throw an error message if you use one of the layer page style commands with an \PName{page style name} that does not correspond with a layer page style. Command \Macro{IfRealLayerPageStyleExists} is similar, but \PName{then code} will only be executed, if \PName{page style name} itself is the name of a layer page style. So \PName{else code} will even be executed, if \PName{page style name} is an alias name of a layer page style or the alias name of an alias name of \dots\ a layer page style.% \EndIndex{Cmd}{IfRealLayerPageStyleExists}% \EndIndex{Cmd}{IfLayerPageStyleExists}% \begin{Declaration} \Macro{IfLayerAtPageStyle}% \Parameter{page style name}\Parameter{layer name}% \Parameter{then code}\Parameter{else code}\\ \Macro{IfSomeLayerAtPageStyle}% \Parameter{page style name}\Parameter{layer list}%^ \Parameter{then code}\Parameter{else code}\\ \Macro{IfLayerAtPageStyle}% \Parameter{page style name}\Parameter{layer list}% \Parameter{then code}\Parameter{else code}% \end{Declaration} \BeginIndex{Cmd}{IfLayerAtPageStyle}% \BeginIndex{Cmd}{IfSomeLayersAtPageStyle}% \BeginIndex{Cmd}{IfLayersAtPageStyle}% Command \Macro{IfLayerAtPageStyle} may be used to test, whether or not a layer named \PName{layer name} is a member of the layer list of a given page style. If the test is true, the \PName{then code} will be executed. If the layer is not a member of the layer list of \PName{page style name}, the \PName{else code} will be executed. Commands \Macro{IfSomeLayerAtPageStyle} and \Macro{IfLayersAtPageStyle} do not only test one layer but several layers at a given, comma separated \PName{layer list}. \Macro{IfSomeLayerAtPageStyle} will execute the \PName{then code} if \emph{at least one} of the layers at \PName{layer list} is a member of the layer list of \PName{page style name}. In difference \Macro{IfLayersAtPageStyle} executes the \PName{then code} only if \emph{all} of the layers at \PName{layer list} are members of the layer list of \PName{page style name}.% \EndIndex{Cmd}{IfLayersAtPageStyle}% \EndIndex{Cmd}{IfSomeLayersAtPageStyle}% \EndIndex{Cmd}{IfLayerAtPageStyle} \begin{Declaration} \Macro{DestroyRealLayerPageStyle}\Parameter{page style name} \end{Declaration} \BeginIndex{Cmd}{DestroyRealLayerPageStyle}% Command \Macro{DestroyRealLayerPageStyle} makes the page style named \PName{page style name} undefined, if and only if it is a layer page style. Nothing will be happen if it is an alias name of a layer page style, if it is another page style, or if it is not a page style. If \PName{page style name} is the name of the current page style the current page style will become a kind of empty page style. If the special page style\,---\,this may be set using \Macro{thispagestyle}\,---\,is \PName{page style name}, this will be simply reset. So the previous \Macro{thispagestyle} will become invalid. Note, the layers of the page style will not be destroyed automatically. If you want to destroy the layers too, you may use % Umbruchkorrektur \begin{lstcode}[belowskip=\dp\strutbox] \ForEachLayerOfPageStyle{...}{\DestroyLayer{#1}} \end{lstcode} \emph{before} destroying the layer page style. The command is intended to be used inside the auto-remove code of an interface See \autoref{sec:scrlayer.enduserinterfaces} below for more information about auto-remove code.% \EndIndex{Cmd}{DestroyRealLayerPageStyle} \LoadCommon{20} % \section{Height of Page Head and Foot} \LoadCommon{21} % \section{Manipulation of Defined Page Styles} \section{End User Interfaces} \seclabel{enduserinterfaces} Package \Package{scrlayer} provides an interface to define and manage (concurrent) end user interfaces. Maybe future releases of \KOMAScript{} will provide parts of this by package \Package{scrbase} and remove those commands from \Package{scrlayer}. But currently this part if \Package{scrlayer} is very experimental, so package \Package{scrlayer} provides its own interface definition commands. Currently you should not depend on correct working of auto-removing a concurrent end user interface. Instead you should avoid using concurrent end user interfaces. This section only describes the interface commands for defining end user interfaces. This is not interesting for end users, but only for authors of end user interfaces. End users will find information about the end user interfaces in the sections about the particular end user interface, e.g., \autoref{cha:scrlayer-scrpage}, \autoref{cha:scrlayer-scrpage-experts}, and \autoref{cha:scrlayer-notecolumn}. \begin{Declaration} \Macro{scrlayerInitInterface}\OParameter{interface name} \end{Declaration} \BeginIndex{Cmd}{scrlayerInitInterface}% Command \Macro{scrlayerInitInterface} registers a new interface. The \PName{interface name} must be unique. If you try to initialise an already initialised interface an error will occur. This command is obligatory and mandatory for interfaces. It should be the first interface command and therefore has been described first. If the optional argument is omitted, \PValue{\Macro{@currname}.\Macro{@currext}} will be used instead. For classes and packages this will be the file name of the class or package while loading the class or package. But you may use any sequence of characters with category letter or other.% \EndIndex{Cmd}{scrlayerInitInterface} \begin{Declaration} \KOption{forceoverwrite}\PName{simple switch}\\ \KOption{autoremoveinterfaces}\PName{simple switch}\\ \Macro{scrlayerAddToInterface}% \OParameter{interface name}\Parameter{command}\Parameter{code}\\ \Macro{scrlayerAddCsToInterface}% \OParameter{interface name}\Parameter{command sequence}\Parameter{code} \end{Declaration} \BeginIndex{Option}{forceoverwrite}% \BeginIndex{Option}{autoremoveinterfaces}% \BeginIndex{Cmd}{scrlayerAddToInterface}% \BeginIndex{Cmd}{scrlayerAddCsToInterface}% One of the special features of end user interfaces is that they should register all interface dependent commands (also known as \emph{macros}). You may do this using \Macro{scrlayerAddToInterface}%^^A . If your interface generates macros not only at load time but also at run time or if the interface name should not be the class's or package's name, you have to use the optional argument to add the command to a dedicated interface. An error will occur, if the interface has not been initialised before. The first mandatory argument is the \PName{command}\footnote{The \PName{command} consists of the backslash followed by a \PName{command sequence} consisting of characters with category code letter or one other character, or \PName{command} consists of one active character (without backslash).} that should be added to the interface. If the command can be added to the interface, it will be added to the interface, will be set to \Macro{relax} and \PName{code} will be executed. You can use, e.g., \Macro{newcommand}\PName{command} inside of \PName{code} to define \PName{command}. But when can a command be defined? If a command is undefined or \Macro{relax} it can be defined. If a command has already been defined and registered for another interface \emph{and} if \KOMAScript{} option \Option{autoremoveinterface} has been switched on, the other interface will be removed automatically and the new command will be set to \Macro{relax} and will be registered for the given interface. If a command has already been defined but is not part of another interface \emph{and} if \KOMAScript{} option \Option{forceoverwrite} has been switched on, the command will be set to \Macro{relax} and will be registered for the given interface. Command \Macro{scrlayerAddCsToInterface} is similar to \Macro{scrlayerAddToInterface} but does not expect a command as first, mandatory argument, but a command sequence\footnote{A command sequence may consist of any characters with category code letter or other.}.% \EndIndex{Cmd}{scrlayerAddCsToInterface}% \EndIndex{Cmd}{scrlayerAddToInterface} \EndIndex{Option}{autoremoveinterfaces}% \EndIndex{Option}{forceoverwrite}% \begin{Declaration} \Macro{scrlayerOnAutoRemoveInterface}%^^A \OParameter{interface name}\Parameter{code} \end{Declaration} \BeginIndex{Cmd}{scrlayerOnAutoRemoveInterface}% Command \Macro{scrlayerOnAutoRemoveInterface} registers \PName{code} to be executed, if the interface will be automatically removed (see \Option{autoremoveinterfaces} prior in this section). This may be used, e.g., to automatically destroy layers or page styles (see \Macro{DestroyLayer}, \Macro{DestroyAliasPageStyle}, and \Macro{DestroyRealLayerPageStyle}).% \EndIndex{Cmd}{scrlayerOnAutoRemoveInterface}% % \EndIndex{}{layer} \EndIndex{Package}{scrlayer} %%% Local Variables: %%% mode: latex %%% mode: flyspell %%% coding: us-ascii %%% ispell-local-dictionary: "en_GB" %%% TeX-master: "../guide" %%% End: