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

Chapter 17: Defining Layers and Page Styles Using scrlayer

388

Table 17.1.: Options for the definition of layers (Continuation)

align=alignment characters

The alignment characters define the desired alignment of the layer. Each

alignment character

influences either, how argument length of option hoffset

or voffset will be used. Several 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 alignment character s are:

b

– align the layer at its bottom edge; the value of voffset is interpreted as the

distance from the top edge of the paper to the bottom edge of the layer.

c

– align the layer at its centre; the values of voffset and hoffset are interpreted

as the distance from the top left corner of the paper to the centre of the layer.

l

– align the layer at its left edge: the value of hoffset is interpreted as the distance

from the left edge of the paper to the left edge of the layer.

r

– align the layer at its right edge; the value of hoffset is interpreted as the

distance from the left edge of the paper to the right edge of the layer.

t

– align the layer at its top edge; the value of voffset is interpreted as the distance

from the top edge of the paper to the top edge of the layer.

area={hoffset }{voffset }{width }{height }

The composed option results in hoffset=hoffset , voffset=voffset , width=

width

, height=height .

v3.18

backandforeground

This option removes any foreground or background restriction of the layer. Generally

usage of this option makes no sense, but it is provided for completeness of the user

interface. The option does not expect any value.

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.

. . .

Chapter 17: Defining Layers and Page Styles Using scrlayer

389

Table 17.1.: Options for the definition of layers (Continuation)

bottommargin

The composed option sets hoffset, voffset, width, height, and align to hori-

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

clone=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 layer name . Note, that layer

name

has to be fully expandable and should expand to letters only. Some additional

characters are tolerated, but are not recommended!

contents=code

The code will be expanded whenever the layer is printed. So the code is what you

will see. Code validity is not checked. So errors in code may result in several failures

on each page, that prints the layer.

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

v3.18

everypage

This is a combination of oddorevenpage and floatornonfloatpage. The option

does not expect any value.

everyside

This option removes any restriction of the layer to single side or double side printing.

This is also the default of layers. The option does not expect any value.

v3.18

floatornonfloatpage

This option removes any restriction of the layer to float or non-float pages. So the

layer will be printed independent of whether a page is a float page or not. This is

also the default of layers. The option does not expect any value.

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.

. . .

Chapter 17: Defining Layers and Page Styles Using scrlayer

390

Table 17.1.: Options for the definition of layers (Continuation)

foot

The composed option sets hoffset, voffset, width, height, and align to hori-

zontally span the text area and vertically span the page footer defined by the new

L

A

TEX length \footheight.

footskip

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally 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 \footskip).

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.

head

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally span the text area and vertically span the page head defined by usual L

A

TEX

length \headheight.

headsep

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally span the text area and vertically span the distance between the page head and

the text area.

height=length

Sets the height of the layer. Note, that length can either be a L

A

TEX length, declared

using \newlength, or a TEX length, declared using \newdimen or \newskip, a length

value like 10 pt, or a dimensional expression using +, -, /, *, (, and ). For more

information about valid dimensional expressions see [

Tea98

, section 3.5].

hoffset=length

Sets the offset of the layer (depending on 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 height

for more information about valid content of length .

. . .

Chapter 17: Defining Layers and Page Styles Using scrlayer

391

Table 17.1.: Options for the definition of layers (Continuation)

innermargin

The composed option sets hoffset, voffset, width, height, and align to horizon-

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

leftmargin

The composed option sets hoffset, voffset, width, height, and align to horizon-

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

v3.19

mode=mode

The primary option defines the mode for the layer output. Default is mode=text.

The Baseline of the first text line will be placed the height of one standard text line

below the top edge of the layer. Therefore the text output will be top aligned in the

layer. In picture mode the layer spans a picture environment with the origin in

the bottom left corner of the layer. The also available raw mode current is the same

like text mode .

Changing the mode of a layer generally can move the contents. Additionally, i. e.,

picture mode

provides additional commands that result in errors with another mode .

Therefore, generally it makes no sense to change the mode of a layer after it’s initial

declaration!

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.

v3.18

oddorevenpage

Removes any restriction of the layer to odd or even pages. So it will be printed

independently of whether a page is odd or even. This is also the default of layers.

The option does not expect any value.

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.

. . .

Chapter 17: Defining Layers and Page Styles Using scrlayer

392

Table 17.1.: Options for the definition of layers (Continuation)

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.

outermargin

The composed option sets hoffset, voffset, width, height, and align to horizon-

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

page

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally and vertically span the whole paper from the left edge to the right edge and

the top edge to the bottom edge.

v3.16

pretocontents=code

Value code will be added at the very beginning of the current value of attribute

contents

. So the new content will be generated in front of the already existing

content. For more information about the handling of code see option contents.

rightmargin

The composed option sets hoffset, voffset, width, height, and align to horizon-

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

textarea

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally and vertically span the whole text area from the left edge to the right edge and

the top edge to the bottom edge.

topmargin

The composed option sets hoffset, voffset, width, height, and align to horizon-

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

. . .

Chapter 17: Defining Layers and Page Styles Using scrlayer

393

Table 17.1.: Options for the definition of layers (Continuation)

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.

v3.18

unrestricted

This option removes all output restrictions of the layer. It is a combination of

backandforeground

, everyside, and floatornonfloatpage. The option does not

expect any value.

voffset=length

Sets the offset of the layer (depending on 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 height

for more information about valid content of length .

width=length

Sets the width of the layer. See height for more information about valid content of

length

.

\layerhalign

\layervalign

\layerxoffset

\layeryoffset

\layerwidth

\layerheight

These commands are valid during output of the layer’s contents only. So they can only be

used inside the code of option contents of the previously described commands. In this case

they give the effective alignment, 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.

The primary layer attribute align is mapped to \layerhalign

v3.19

and \layervalign. The

horizontal values l and r are copied to \layerhalign. The vertical values r and b are copied to

\layervalign

. The also horizontal and vertical value c is copied to both commands. If align

has contradictory values, only the last one is copied. Therefore the resulting \layerhalign is

either l, c, or r and the resulting \layervalign is either r, c, or b.

Redefinition of the commands to change the stored values is strictly forbidden and would

result in unpredictable issues.

Chapter 17: Defining Layers and Page Styles Using scrlayer

394

\LenToUnit{length }

This

v3.19

command has been copied from eso-pic 2.0f. It converts lengths into multiples of

\unitlength

. It can be used everywhere L

A

TEX expects picture coordinates or \unitlength-

depending values. For more information see [

Nie15

] and the following descriptions of \putUR,

\putLL

, and \putLR. If the command is already defined, e. g., by loading eso-pic before scrlayer,

the package does not define it again.

It should be noted at this point that using package picture (see [

Obe09

]) supersedes

\LenToUnit

more or less. The package extends environment picture and the picture com-

mands to accept L

A

TEX lengths directly.

\putUL{content }

\putUR{content }

\putLL{content }

\putLR{content }

\putC{content }

You

v3.19

can use these commands inside the value of primary layer option contents, if the layer is

declared with mode=picture. In that case, \putUL places the content relative to the upper

left corner of the layer and therefore is the same like \put(0,\LenToUnit{\layerheight}).

\putUR

places the content relative to the upper right corner of the layer and therefore

is the same like \put(\LenToUnit{\layerwidth},\LenToUnit{\layerheight}). \putLL

places the content relative to the lower left corner of the layer and therefore is the same

like \put(0,0). \putLR places the content relative to the lower right corner and therefore

is the same like \put(\LenToUnit{\layerwidth},0). Last but not least \putC places the

content

relative to the centre of the layer.

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}}}%

}

Chapter 17: Defining Layers and Page Styles Using scrlayer

395

]{showtextarea}

\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 29

.

For more information about command \DeclareNewPageStyleByLayers see the description

later in

section 17.5

,

page 398

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

Chapter 17: Defining Layers and Page Styles Using scrlayer

396

\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

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 335

).

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.

Chapter 17: Defining Layers and Page Styles Using scrlayer

397

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

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.