Note: This document is a translation of the German koma script manual

Example: You want to investigate, how accurate DIV=classic sets the height of the text

area to the width of the page size. So you declare a layer that not only border the

text area, but also places a circle with paper width as diameter dimension into the

centre of the text area:

\documentclass[DIV=classic]{scrartcl}

\usepackage{pict2e}

\usepackage{scrlayer}

\DeclareNewLayer[%

textarea,background,mode=picture,

contents={%

\putLL{\line(1,0){\LenToUnit{\layerwidth}}}%

\putLR{\line(0,1){\LenToUnit{\layerheight}}}%

\putUR{\line(-1,0){\LenToUnit{\layerwidth}}}%

\putUL{\line(0,-1){\LenToUnit{\layerheight}}}%

\putC{\circle{\LenToUnit{\paperwidth}}}%

}

]{showtextarea}

347

Chapter 17.

\DeclareNewPageStyleByLayers{test}{showtextarea}

\pagestyle{test}

\begin{document}

\null

\end{document}

You will see that typearea’s mapping to an integer DIV value is very accurate in

this example.

For more information about the sketched Middle Age method of generating a text area see

section 2.3

,

page 28

.

For more information about command \DeclareNewPageStyleByLayers see the description

later in

section 17.5

,

page 350

. In short: It defines a new page style using the newly declared

layer.

\GetLayerContents{layer name }

This

v3.16

command results in the whole content of a layer. You have to note that using this

command inside the code of the layer attributes contents, addcontents, or pretocontents

can result in an infinite recursion, if the content of the current layer is referenced. You yourself

should avoid such situations!

\IfLayerExists{string }{then-code }{else-code }

This command may be used to execute code depending on whether or not a layer has been

defined already. If the layer exists then-code will be executed, otherwise 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.

\DestroyLayer{layer name }

This command sets all macros corresponding with the layer with given layer name to \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 \DeclareNewLayer or

\ProvideLayer

, but cannot be changed using \RedeclareLayer or \ModifyLayer any longer.

The command is intended to be used inside \scrlayerOnAutoRemoveInterface to remove

layers, which have been defined using removable macros of an interface, whenever the interface

would be removed.

\layercontentsmeasure

The command \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

348

Chapter 17.

is used internally, if option 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.

17.5. Declaration and Management of Page Styles

Until now we know layers, but we do not know how to use them. The perhaps astonishing

answer is: with page styles. In L

A

TEX, 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 oddpage

and 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

background

and foreground.

So it suggests itself to declare page styles as a list of layers. But instead of having only

four attributes oddpage, evenpage, background, and foreground all the attributes of layers

shown in

section 17.4

may be used.

The outcome of all such considerations is that layer page styles are one type of page styles

scrlayer provides. A layer page style consists of layers and several hooks. For description of

layers see

section 17.4

. The 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

\AtBeginDocument

(see [

Tea05b

]) or \BeforeClosingMainAux (see

page 289

).

Alias page styles are another type of page styles provided by 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 scrlayer page styles, but possible for all page styles.

\currentpagestyle

Package scrlayer patches \pagestyle to set \currentpagestyle to the currently active

page style. Note, \thispagestyle does not change \currentpagestyle. But if you use

\thispagestyle

the result of \currentpagestyle may be changed while executing the L

A

TEX

output routine. However, this change will only occur, if \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

\pagestyle

to set \currentpagestyle. The patch has been made for usage with other page

styles. Additionally, \currentpagestyle is empty before the first \pagestyle after loading

349

Chapter 17.

scrlayer. So if you define an end user page style interface, it may be useful to use an implicit

\pagestyle

to set the current page style to a default page style.

\BeforeSelectAnyPageStyle{code }

\AfterSelectAnyPageStyle{code }

The command \BeforeSelectAnyPageStyle adds code to the hook that will be executed in-

side of \pagestyle just before the page style will be selected. You may use #1 as a placeholder

for the argument of \pagestyle.

The command \AfterSelectAnyPageStyle is similar, but the code will be executed just

after the page style has been selected and after \currentpagestyle has been set to the name

of the real page style.

Note, code of both commands will be executed only if a page style will be selected using

\pagestyle

, but not, e. g., if a page style will be selected using \thispagestyle. Note also,

you cannot remove code from the hook after adding it. But the code will be added locally,

so you may use a group to limit the scope of code .

\DeclarePageStyleAlias{alias page style name }{original page style name }

\DeclareNewPageStyleAlias{alias page style name }{original page style name }

\ProvidePageStyleAlias{alias page style name }{original page style name }

\RedeclarePageStyleAlias{alias page style name }{original page style name }

These commands may be used to define a page style with name alias page style name that

is simply an alias for an already existing page style with name original page style name . If

there is already a page style alias page style name , then using \DeclarePageStyleAlias

or \RedeclarePageStyleAlias will destroy the alias before recreating it.

\DeclareNewPageStyleAlias

will throw an error message, if a page style 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.

\ProvidePageStyleAlias

will define the alias only if a page style alias page style name

has not been defined before. If a page style alias page style name already exists nothing

will be done.

\RedeclarePageStyleAlias

expects an already existing page style alias page style

name

. It will destroy that page style and afterwards define the alias. If the page style alias

page style name

does not exist, then you will get an error.

\DestroyPageStyleAlias{page style name }

This command makes the page style with given page style name L

A

TEX-undefined, if it is

an alias for another page style. Afterwards, the page style may be defined newly with, e.g.,

\DeclareNewAliasPageStyle

or \ProvideAliasPageStyle.

The command is intended to be used inside of \scrlayerOnAutoRemoveInterface to re-

move page styles that have been declared by an interface and use removable macros of that

interface.

350

Chapter 17.

\GetRealPageStyle{page style name }

The command will result in the (recursive) real page name of the page style, if the page style

with given name 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 page style name , the result would be simply

page style name

. The command is fully expandable and may be used, e.g., in the second

argument of \edef.

\DeclarePageStyleByLayers[option list ]{page style name }{layer list }

\DeclareNewPageStyleByLayers[option list ]{page style name }{layer list }

\ProvidePageStyleByLayers[option list ]{page style name }{layer list }

\RedeclarePageStyleByLayers[option list ]{page style name }{layer list }

These commands declare a page style with page style name . The page style will consist of

the layers given in layer list , a comma separated list of layer names. Note, the page style

name

and the layer names at the layer list must be fully expandable and should expand

to letters. Several other characters are tolerated, but, nevertheless, not recommended.

The option list is a comma separated list of key =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 hooks. See the introduction to this section for more general

information about hooks. See

table 17.2

for detailed information on specific hooks.

Table 17.2.: The hook options for page styles (in order of execution)

onselect=code

Execute code whenever the page style is selected using, e.g., \pagestyle. Note,

\thispagestyle

does not select the page style immediately, but asynchronously

inside L

A

TEX’s output routine.

oninit=code

Execute code whenever the output of page style’s layers is initialised. Note, this

is done twice for every page: once for background layers and once for foreground

layers.

ononeside=code

Execute code whenever the output of page style’s layers in single-side mode is ini-

tialised. Note, this is done twice for every page: once for background layers and once

for foreground layers.

. . .

351

Chapter 17.

Table 17.2.: The hook options for page styles (Continuation)

ontwoside=code

Execute code whenever the output of page style’s layers in two-side mode is ini-

tialised. Note, this is done twice for every page: once for background layers and

once for foreground layers.

onoddpage=code

Execute code whenever the output of page style’s layers on an odd page is initialised.

Note, this is done twice for every page: once for background layers and once for

foreground layers. Note also that in single-side mode all pages are odd pages, not

only pages with odd page numbers.

onevenpage=code

Execute code whenever the output of page style’s layers on an even page is initialised.

Note, this is done twice for every page: once for background layers and once for

foreground layers. Note also that there are not even pages in single-side mode, but

all pages are odd pages, not only pages with odd page numbers.

onfloatpage=code

Execute code whenever the output of page style’s layers on a float page are ini-

tialised. Note, this is be done twice for every page: once for background layers and

once for foreground layers. Note also that float pages are only those pages with

p-placed floating objects.

onnonfloatpage=code

Execute code whenever the output of page style’s layers on a non-float page is

initialised. Note, this is done twice for every page: once for background layers and

once for foreground layers. Note 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.

onbackground=code

Execute code whenever the output of page style’s layers in the background of a page

is initialised. Note, this is done once for every page.

onforeground=code

Execute code whenever the output page style’s layers in the foreground of a page is

initialised. Note, this is done once for every page.

The difference of \DeclarePageStyleByLayers and \DeclareNewPageStyleByLayers is

that \DeclareNewPageStyleByLayers will result in an error, if a page style with name page

style name

already exists. Note, declaring a page style, which is an alias of another page

352

Chapter 17.

style (see \DeclareAliasPageStyle prior in this section), will not re-declare the page style

itself, but it’s real page style (see \GetRealPageStyle prior in this section).

The difference of \DeclarePageStyleByLayers and \ProvidePageStyleByLayers is that

\ProvidePageStyleByLayers

will simply do nothing, if there’s already a page style with name

page style name

. In difference to \DeclareNewPageStyleByLayers it will not raise an error.

The difference of \DeclarePageStyleByLayers and \RedeclarePageStyleByLayers is,

that \RedeclarePageStyleByLayers may be used only if the real page style of page style

name

already exists. Otherwise an error occurs.

Please have also a look at the notes to following pseudo page style @everystyle@.

@everystyle@

empty

There are two default layer page styles that are somehow special.

The first one is

@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 \ForEachLayerOfPageStyle, \AddLayerToPageStyleBeforeLayer, or

\AddLayerToPageStyleAfterLayer

process only the layers of the page style that has been

referenced but not the layers implicated by @everystyle@.

The other somehow special page style is empty. Normally page style empty is defined by the

L

A

TEX kernel, to be a page style without page head or page foot. 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 L

A

TEX kernel’s empty page style is that it also

executes the layers of special layer page style @everysel@.

onpsselect=code

onpsinit=code

onpsoneside=code

onpstwoside=code

onpsoddpage=code

onpsevenpage=code

onpsfloatpage=code

onpsnonfloatpage=code

onpsbackground=code

onpsforeground=code

There’s also a KOMA-Script option for each of those hooks. The names of the KOMA-Script

options are similar to the names of the page style options, but with “ps” inserted behind “on”.

The value of the KOMA-Script options are the initial defaults of the corresponding hooks.

These defaults will be extended at every declaration of page style hook options via option

353

Chapter 17.

list

. You may remove the default, using \ModifyLayerPageStyleOptions described later

in this section.

deactivatepagestylelayers=simple switch

\ForEachLayerOfPageStyle{page style name }{code }

\ForEachLayerOfPageStyle*{page style name }{code }

As long as KOMA-Script option deactivatepagestylelayers has not been activated com-

mand \ForEachLayerOfPageStyle can be used to process code for every member layer of

page style name

’s layers list. Inside of code the place holder #1 may be used to reference

the name of the current layer.

Example: If you want to print the names of all layers of page style scrheadings, you may

us:

\let\commaatlist\empty

\ForEachLayerOfPageStyle{scrheadings}{%

\commaatlist#1\gdef\commaatlist{, }}

Usage of \gdef instead of \def is necessary in the example above, because

\ForEachLayerOfPageStyle

executes the code inside of a group to minimise side effects.

Here \gdef redefines \commaatlist globally, so it would be still valid at the execution of

code

for the next layer.

Alternatively,

v3.18

you can use \def but the star variant \ForEachLayerOfPageStyle*.

This type does not use an additional group for executing code .

On the

other hand the user has to take care on side effects of code , i. e., deactiva-

tion of all layers using deactivatepagestylelayers=true in code would persist after

\ForEachLayerOfPageStyle*

.

Several other commands of scrlayer also use \ForEachLayerOfPageStyle internally. So these

also do not process any layer if KOMA-Script option deactivatepagestylelayers would be

activated. So you may use this options, e.g., to hide all layers of all layer page styles.

\AddLayersToPageStyle{page style name }{layer list }

\AddLayersAtBeginOfPageStyle{page style name }{layer list }

\AddLayersAtEndOfPageStyle{page style name }{layer list }

\RemoveLayersFromPageStyle{page style name }{layer list }

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 page style name . The layers are given

by a comma separated layer list .

The commands \AddLayersToPageStyle and \AddLayersAtEndOfPageStyle add all layers

of the comma separated list of layers layer list at the end of the layer list of layer page style

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.

354

Chapter 17.

Command \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 layer list . The

first layer at layer list will be added first, the second layer will be added second and so on.

So with \AddLayersAtBeginOfPageStyle the last layer at layer list will become the new

first layer of the layer list of layer page style page style name .

Command \RemoveLayersFromPageStyle may be used to remove layers from the layer list

of layer page style page style name instead of adding them. Note, layers, which are part

of 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.

\AddLayersToPageStyleBeforeLayer{page style name }{layer list }{reference layer name }

\AddLayersToPageStyleAfterLayer{page style name }{layer list }{reference layer name }

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 layer list

will be same in the layer list of page style name after adding. If the reference layer named

reference layer name

is not part of the layer list of the layer page style, nothing happens.

\UnifyLayersAtPageStyle{page style name }

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 \UnifyLayersAtPageStyle to remove all dupes of layers from the layer list of a layer

page style.

Note, 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 \UnifyLayersAtPageStyle.

\ModifyLayerPageStyleOptions{page style name }{option list }

\AddToLayerPageStyleOptions{page style name }{option list }

Command \ModifyLayerPageStyleOptions may be used to modify the page style options of

a layer page style. Only options at the comma separated option list will be set to the new

values given in option list if the new value is not empty. Options, which are not at option

list

, will stay unchanged. If you want to set an option to do nothing you may use value

\relax

. Note, setting an option to a new value using \ModifyLayerPageStyleOptions will

remove the previous value including the global default value.

\AddToLayerPageStyleOptions

differs from \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 option list .

355

Chapter 17.

\IfLayerPageStyleExists{page style name }{then code }{else code }

\IfRealLayerPageStyleExists{page style name }{then code }{else code }

Command \IfLayerPageStyleExists tests, whether or not the real page style of page style

name

is a layer page style. If the test is true, then code will be executed. If page style

name

is neither a layer page style, nor an alias of a layer page style, nor an alias of an alias of

. . . a layer page style, 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 page style

name

that does not correspond with a layer page style.

Command \IfRealLayerPageStyleExists is similar, but then code will only be executed,

if page style name itself is the name of a layer page style. So else code will even be

executed, if page style name is an alias name of a layer page style or the alias name of an

alias name of . . . a layer page style.

\IfLayerAtPageStyle{page style name }{layer name }{then code }{else code }

\IfSomeLayerAtPageStyle{page style name }{layer list }{then code }{else code }

\IfLayerAtPageStyle{page style name }{layer list }{then code }{else code }

Command \IfLayerAtPageStyle may be used to test, whether or not a layer named layer

name

is a member of the layer list of a given page style. If the test is true, the then code

will be executed. If the layer is not a member of the layer list of page style name , the else

code

will be executed.

Commands \IfSomeLayerAtPageStyle and \IfLayersAtPageStyle do not only test one

layer but several layers at a given, comma separated layer list . \IfSomeLayerAtPageStyle

will execute the then code if at least one of the layers at layer list is a member of the

layer list of page style name . In difference \IfLayersAtPageStyle executes the then code

only if all of the layers at layer list are members of the layer list of page style name .

\DestroyRealLayerPageStyle{page style name }

Command \DestroyRealLayerPageStyle makes the page style named page style name un-

defined, 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 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 \thispagestyle —

is page style name , this will be simply reset. So the previous \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

\ForEachLayerOfPageStyle{...}{\DestroyLayer{#1}}

before

destroying the layer page style.

The command is intended to be used inside the auto-remove code of an interface See

sec-

tion 17.8

below for more information about auto-remove code.

356

Chapter 17.