path: root/doc/user/bgr_boxs

@Section
    @Title { Boxes and rules }
    @Tag { boxes }
@Begin
@PP
The @Code "@Box" symbol causes the following object to be enclosed in a
box. @Index @Code "@Box"
box:
@ID @OneRow @Code {
"@QuotedDisplay @Box {"
"@CentredDisplay @Heading Cheating"
"The Department uses assignments ... of that student alone."
"}"
}
The result of this is
@QuotedDisplay @Box {
@CentredDisplay @Heading Cheating
The Department uses assignments both as a teaching device and as a
major component of its assessment of each student.  It therefore
requires that all programs, exercises etc. handed in bearing an
individual student's name be the work of that student alone.
}
showing that a box may enclose an arbitrarily complicated object.
@PP
The @Code "@Box" symbol has a @Code margin option which determines the
box. @RawIndex @Code "@Box"
box.margin @SubIndex { @Code "margin" option }
margin between the box and what it encloses.  For example,
@ID @OneRow @Code {
"@Box"
"    margin { 0.1c }"
"{}"
}
requests a box with a 0.1 centimetre margin enclosing an empty object,
so the result is a square whose width and height are 0.2 centimetres:
@ID @Box margin { 0.1c } {}
If the @Code "margin" option is omitted, it is assigned the default
value {@Code "0.3f"}, which means 0.3 times the current font size.  It
is very useful to tie the margin to the font size in this way, because
large headings (in overhead transparencies, say) need large margins.
@PP
There is a @Code "linewidth" option which determines the width
box.linewidth @SubIndex { @Code "linewidth" option }
(thickness) of the line drawn around the boundary of the box:
@ID @OneRow @Code {
"@Box"
"    linewidth { 0.1c }"
"{ Hello world }"
}
produces
@ID @Code {
@Box
    linewidth { 0.1c }
{ Hello world }
}
Lout does not take the line width into account when working out how
large everything is:  as far as Lout is concerned, the line always
has width zero.  If you draw really thick lines you might need a larger
margin and more space near the box.  The default value of @Code linewidth
is empty, which means to use whatever width the PostScript interpreter
in your output device thinks is a good default value.  The special
value @Code "none" for @Code "linewidth" ensures that no line is drawn
around the box at all.
@PP
There is also a @Code "paint" option which paints a background of the
box.paint @SubIndex { @Code "paint" option }
nominated colour:
@ID @Code "@Box paint { grey } WARNING!"
has result
@ID @Box paint { grey } WARNING!
This is quite different from {@Code "grey @Colour @Box WARNING!"},
which produces
@ID grey @Colour @Box WARNING!
The @Code "paint" option may be given any colour from the list in
Section {@NumberOf colour}; its default value is {@Code "none"}, which
is a special value (not a colour) which means no painting.  White paint
comes into its own inside painted boxes:
@ID @Code "@Box paint { nochange } white @Colour { Hello world }"
produces a box painted in whatever colour we happen to be using at
the moment, with white text inside:
@ID @Box paint { nochange } white @Colour { Hello world }
This works because the box is painted before the object it encloses
is drawn on the page.
@PP
Wherever there is a @Code paint option in Lout for painting the background
of something, there is always an accompanying @Code texture option for
box.texture @SubIndex { @Code "texture" option }
applying that paint with the textures described in
Section {@NumberOf textures}.  For example,
@ID @Code "@Box paint { black } texture { brickwork } 50p @Font WARNING!"
produces
@FootNote { As explained in Section {@NumberOf textures}, if you can't
see any textures the problem is probably with your PostScript viewer. }
@ID @Box paint { black } texture { brickwork } 50p @Font WARNING!
If @Code paint is absent or @Code none then @Code texture will have no
effect.  Since textures are naturally lighter than solid colour, you
will usually need darker paint when using textures than when not.
@PP
To set options on a texture within a @Code "texture" option, you can write
@ID @Code "texture { striped @Texture angle { 45d } scale { 2 } }"
mimicking the @Code "@Texture" symbol from Section {@NumberOf textures},
but without any following object.  However, it's clunky to have to type
both @Code texture and {@Code "@Texture"}, so by special arrangement you
can omit the @Code "@Texture" symbol within the @Code "texture" option:
@ID @Code "texture { striped angle { 45d } scale { 2 } }"
The value of the @Code "texture" option may also be an expert's texture
as required by {@Code "@SetTexture"}.  Incidentally, there is no
significance in our laying out all the options along one line.  As always
in Lout, the end of a line and a space mean the same.  We've done it this
way because we think it's the clearest way to lay out the @Code texture option.
@PP
Let's just summarize the painting and texturing possibilities for boxes.
A box has three components: its outline, its background, and its content
(what appears inside).  You can actually set the colour and texture of
all three components independently of each other, with a little trouble:
@ID @OneRow @Code @Verbatim {
black @Colour striped @Texture angle { 45d }
@Box
    paint { lightgrey }
    linewidth { 2p }
    texture { striped angle { 90d } }
darkgrey @Colour striped @Texture scale { 2 } 50p @Font ABC
} 
produces
@CD {
black @Colour striped @Texture angle { 45d }
@Box
    paint { lightgrey }
    linewidth { 2p }
    texture { striped angle { 90d } }
darkgrey @Colour striped @Texture scale { 2 } 50p @Font ABC
} 
The outline colour and texture are the colour and texture from outside
the box; the background colour and texture are always determined by the
@Code paint and @Code texture options; and the colour and texture of
the contents are inherited from outside the box, but can be changed as
shown if desired.  Notice what happens when two textures overstrike:  the
lower one shows through the unpainted parts of the upper one.
@PP
There are @Code "@CurveBox" and @Code "@ShadowBox" symbols that
curvebox. @Index @Code "@CurveBox"
shadowbox. @Index @Code "@ShadowBox"
produce other kinds of boxes:
@CD @Tab
    @Fmta { @Col A ! @Col ! @Col B }
{
@Rowa
    A { @CurveBox { A curve box } }
    B { @ShadowBox { A shadow box } }
}
These also have {@Code "margin"}, {@Code "linewidth"}, {@Code "paint"},
and @Code "texture" options, and @Code "@ShadowBox" has a @Code "shadow"
option which determines the thickness of the shadow (its default value
is {@Code "0.2f"}).
@PP
Boxes are quite at home inside paragraphs, as @Box { a box },
@CurveBox { a curve box }, and @ShadowBox { a shadow box }
show.  Simply proceed as usual:
@ID @Code "... paragraphs, as @Box { a box }, @CurveBox { a curve box }, ..."
Boxes within paragraphs are never broken across two lines.
@PP
There are two symbols for producing horizontal rules.  @Code "@FullWidthRule"
fullwidthrule. @Index @Code "@FullWidthRule"
rules. @Index rules
produces a rule which occupies the full page (or column) width:
@DP @FullWidthRule @DP
More precisely, the rule occupies as much horizontal space as it
legally can.  @Code "@FullWidthRule" produces an object in the usual
way, so you will need paragraph or display symbols to separate it from
preceding and following things.
@PP
A variant called @Code "@LocalWidthRule" is more timid about zooming
localwidthrule. @Index @Code "@LocalWidthRule"
across the whole page:
@ID @Code {
"@OddPageTop { { My lovely document @LP @LocalWidthRule } @Right @PageNum }"
}
will draw a rule under just the three words.  Of course, underlining using
the @Code "@Underline" symbol might be a better way to do this.
@PP
These two rule symbols are handled behind the scenes like the outlines
of boxes.  Both symbols have a @Code "linewidth" option which works
like the one for boxes described above.  In particular, Lout leaves
zero space for the line, no matter how wide you make it.  And to change
the colour or texture of a rule, it must be enclosed in @Code "@Colour"
and @Code "@Texture" symbols:
@ID @Code "chessboard @Texture scale { 2 } @FullWidthRule linewidth { 8p }"
produces
@DP
chessboard @Texture scale { 2 } @FullWidthRule linewidth { 8p }
@DP
Notice how we have made sure that the rule is wide enough to
accommodate two rows of the chessboard texture.  The author's
printer places a thin row of solid colour along the top of
this pattern.  Logically it should not be there; it can be got
rid of by reducing the line width:
@ID @Code "chessboard @Texture scale { 2 } @FullWidthRule linewidth { 7.5p }"
produces
@DP
chessboard @Texture scale { 2 } @FullWidthRule linewidth { 7.5p }
@DP
We can only guess that the problem might be roundoff error.
@End @Section