@c TODO Add new subsection Shapes of objects
@c which would include Slur shapes
-@c with a Known issue: can't modify shapes if there are
+@c with a Known issue: can't modify shapes with 'control-points if there are
@c more than one at the same musical moment
@node Controlling visibility of objects
@subsection Controlling visibility of objects
-@c FIXME Write this section
+@cindex objects, visibility of
+@cindex grobs, visibility of
+@cindex visibility of objects
+
+There are four main ways in which the visibility of layout objects
+can be controlled: their stencil can be removed, they can be made
+transparent, they can be colored white, or their
+@code{break-visibility} property can be overridden. The first
+three apply to all layout objects; the last to just a few -- the
+@emph{breakable} objects. The Learning Manual introduces these
+four techniques, see @rlearning{Visibility and color of objects}.
+
+There are also a few other techniques which are specific to
+certain layout objects. These are covered under Special
+considerations.
+
+@menu
+* Removing the stencil::
+* Making objects transparent::
+* Painting objects white::
+* Using break-visibility::
+* Special considerations::
+@end menu
+
+
+@node Removing the stencil
+@unnumberedsubsubsec Removing the stencil
+
+@cindex stencil, removing
+
+Every layout object has a stencil property. By default this is set
+to the specific function which draws that object. If this property
+is overridden to @code{#f} no function will be called and the object
+will not be drawn. The default action can be recovered with
+@code{\revert}.
+
+@lilypond[quote,verbatim,relative=1]
+a1 a
+\override Score.BarLine #'stencil = ##f
+a a
+\revert Score.BarLine #'stencil
+a a a
+@end lilypond
+
+@node Making objects transparent
+@unnumberedsubsubsec Making objects transparent
+
+@cindex transparent, making objects
+
+Every layout object has a transparent property which by default is
+set to @code{#f}. If set to @code{#t} the object still occupies
+space but is made invisible.
+
+@lilypond[quote,verbatim,relative=2]
+a4 a
+\once \override NoteHead #'transparent = ##t
+a a
+@end lilypond
+
+@node Painting objects white
+@unnumberedsubsubsec Painting objects white
+
+Every layout object has a color property which by default is set
+to @code{black}. If this is overridden to @code{white} the object
+will be indistinguishable from the white background. However,
+if the object crosses other objects and is drawn after them the
+crossings will also be colored white, as can be seen in this
+example:
+
+@c TODO Sometimes the bar lines are not overriden - why not?
+
+@lilypond[quote,verbatim,relative=2]
+a1 a
+\once \override Score.BarLine #'color = #white
+a a
+@end lilypond
+
+@cindex layers
+@cindex printing order
+@cindex overwriting objects
+@cindex objects, overwriting
+@cindex grobs, overwriting
+
+This may be avoided by changing the order of printing the objects.
+Objects in layer 0 are drawn first, then objects in layer 1 and
+finally objects in layer 2. Within one layer, objects drawn later
+overwrite objects drawn earlier. By default all objects are placed
+in layer 0, and the order of drawing is just the order in which the
+objects are processed.
+
+In the example above the white bar line is drawn after the staff
+lines, so overwriting them. To change this, the @code{StaffSymbol}
+object must be placed in a higher layer, say layer 1, so that it is
+drawn later. This override must be encountered before or at the
+time the @code{StaffSymbol} object is created, i.e. at the
+beginning of the staff:
+
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ \once \override Score.StaffSymbol #'layer = #1
+ a1 a
+ \once \override Score.BarLine #'color = #white
+ a a
+ }
+}
+@end lilypond
+
+@node Using break-visibility
+@unnumberedsubsubsec Using break-visibility
+
+@cindex break-visibility
+
+Most layout objects are printed only once, but some like
+bar lines, clefs, time signatures and key signatures, may need
+to be printed twice when a line break occurs -- once at the end
+of the line and again at the start of the next line. Such
+objects are called @emph{breakable}, and have a property, the
+@code{break-visibility} property to control their visibility
+at the three positions in which they may appear -- at the
+start of a line, within a line if they are changed, and at the
+end of a line if a change takes place there.
+
+For example, the time signature
+by default will be printed at the start of the first line, but
+nowhere else unless it changes, when it will be printed at the
+point at which the change occurs. If this change occurs at the
+end of a line the new time signature will be printed at the start
+of the next line and a cautionary time signature will be printed
+at the end of the previous line as well.
+
+This behaviour is controlled by the @code{break-visibility}
+property, which is explained in @rlearning{Visibility and color of
+objects}. This property takes a vector of three booleans which,
+in order, determine whether the object is printed at the end of,
+within the body of, or at the beginning of a line. Or to be more
+precise, before a line break, where there is no line break, or
+after a line break.
+
+Alternatively, seven of the eight combinations may be specified
+by pre-defined functions, defined in @file{scm/output-lib.scm},
+where the last three columns indicate whether the layout objects
+will be visible in the positions shown at the head of the columns:
+
+@multitable @columnfractions .40 .15 .15 .15 .15
+@c TODO check these more carefully
+@headitem Function @tab Vector @tab Before @tab At no @tab After
+@headitem form @tab form @tab break @tab break @tab break
+
+@item @code{all-invisible} @tab @code{'#(#f #f #f)} @ @ @tab no @tab no @tab no
+@item @code{begin-of-line-visible} @tab @code{'#(#f #f #t)} @tab no @tab no @tab yes
+@item @code{end-of-line-visible} @tab @code{'#(#t #f #f)} @tab yes @tab no @tab no
+@item @code{all-visible} @tab @code{'#(#t #t #t)} @tab yes @tab yes @tab yes
+@c The center-visible function is not defined
+@c @item @code{center-visible} @tab @code{'#(#f #t #f)} @tab no @tab yes @tab no
+@item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)} @tab yes @tab yes @tab no
+@item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab no @tab yes @tab yes
+@item @code{center-invisible} @tab @code{'#(#t #f #t)} @tab yes @tab no @tab yes
+@end multitable
+
+The @code{center-visible} function is not pre-defined.
+
+The default settings of @code{break-visibility} depend on the
+layout object. The following table shows all the layout objects
+of interest which are affected by @code{break-visibility} and the
+default setting of this property:
+
+@multitable @columnfractions .3 .3 .4
+
+@headitem Layout object @tab Usual context @tab Default setting
+
+@c omit Ambitus as it appears not to be affected by break-visibility -td
+@c @item @code{Ambitus} @tab as specified @tab @code{begin-of-line-visible}
+@item @code{BarLine} @tab @code{Score} @tab calculated
+@item @code{BarNumber} @tab @code{Score} @tab @code{begin-of-line-visible}
+@c omit the following item until it can be explained -td
+@c @item @code{BreakAlignGroup} @tab @code{Score} @tab calculated
+@item @code{BreathingSign} @tab @code{Voice} @tab @code{begin-of-line-invisible}
+@item @code{Clef} @tab @code{Staff} @tab @code{begin-of-line-visible}
+@item @code{Custos} @tab @code{Staff} @tab @code{end-of-line-visible}
+@item @code{DoublePercentRepeat} @tab @code{Voice} @tab @code{begin-of-line-invisible}
+@c omit KeyCancellation until it can be explained -td
+@c @item @code{KeyCancellation} @tab ?? @tab @code{begin-of-line-invisible}
+@item @code{KeySignature} @tab @code{Staff} @tab @code{begin-of-line-visible}
+@c omit LeftEdge until it can be explained -td
+@c @item @code{LeftEdge} @tab @code{Score} @tab @code{center-invisible}
+@item @code{OctavateEight} @tab @code{Staff} @tab @code{begin-of-line-visible}
+@item @code{RehearsalMark} @tab @code{Score} @tab @code{end-of-line-invisible}
+@item @code{TimeSignature} @tab @code{Staff} @tab @code{all-visible}
+
+@end multitable
+
+The example below shows the use of the vector form to control the
+visibility of barlines:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+f4 g a b
+f4 g a b
+% Remove bar line at the end of the current line
+\once \override Score.BarLine #'break-visibility = #'#(#f #t #t)
+\break
+f4 g a b
+f4 g a b
+@end lilypond
+
+Although all three components of the vector used to override
+@code{break-visibility} must be present, not all of them are
+effective with every layout object, and some combinations may
+even give errors. The following limitations apply:
+
+@itemize @bullet
+@item Bar lines cannot be printed at start of line.
+@item A bar number cannot be printed at the start of the first
+line unless it is set to be different from 1.
+@item Clef -- see below
+@item Double percent repeats are either all printed or all
+suppressed. Use begin-of line-invisible to print and
+all-invisible to suppress.
+@item Key signature -- see below
+@item OctavateEight -- see below
+@end itemize
+
+@node Special considerations
+@unnumberedsubsubsec Special considerations
+
+@strong{@emph{Visibility following explicit changes}}
+
+@cindex key signature, visibility following explicit change
+@cindex explicitKeySignatureVisibility
+@cindex clef, visibility following explicit change
+@cindex explicitClefVisibility
+
+The @code{break-visibility} property controls the visibility of
+key signatures and changes of clef only at the start of lines,
+i.e. after a break. It has no effect on the visibility of the
+key signature or clef following an explicit key change or an
+explicit clef change within or at the end of a line. In the
+following example the key signature following the explicit change
+to B-flat major is still visible, even though @code{all-invisible}
+is set.
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+% Try to remove all key signatures
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b
+\break
+f4 g a b
+f4 g a b
+@end lilypond
+
+The visibility of such explicit key signature and clef changes is
+controlled by the @code{explicitKeySignatureVisibility} and
+@code{explicitClefVisibility} properties. These are the equivalent
+of the @code{break-visibility} property and both take a vector of
+three booleans or the predefined functions listed above, exactly like
+@code{break-visibility}. Both are properties of the Staff context,
+not the layout objects themselves, and so they are set using the
+@code{\set} command. Both are set by default to @code{all-visible}.
+These properties control only the visibility of key signatures and
+clefs resulting from explicit changes and do not affect key
+signatures and clefs at the beginning of lines;
+@code{break-visibility} must still be overridden in the appropriate
+object to remove these.
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+@strong{@emph{Visibility of cautionary accidentals}}
+
+To remove the cautionary accidentals printed at an explicit key
+change, set the Staff context property @code{printKeyCancellation}
+to @code{#f}:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.printKeyCancellation = ##f
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+With these overrides only the accidentals before the notes remain
+to indicate the change of key.
+
+@c TODO Add visibility of cautionary accidentals before notes
+
+@strong{@emph{Automatic bars}}
+
+@cindex automaticBars
+@cindex bar lines, suppressing
+
+As a special case, the printing of bar lines can also be turned off
+by setting the @code{automaticBars} property in the Score context.
+If set to @code{#f}, bar lines will not be printed automatically;
+they must be explicitly created with a @code{\bar} command. Unlike
+the @code{\cadenzaOn} predefined command, measures are still counted.
+Bar generation will resume according to that count if this property
+is later set to @code{#t}. When set to @code{#f}, line breaks can
+occur only at explicit @code{\bar} commands.
+
+@c TODO Add example
+
+@strong{@emph{Octavated clefs}}
+
+@cindex octavated clefs, visibility of
+@cindex visibility of octavated clefs
+@cindex clefs, visibility of octavation
+
+The small octavation symbol on octavated clefs is produced by the
+@code{OctavateEight} layout object. Its visibility is controlled
+independently from that of the @code{Clef} object, so it is
+necessary to apply any required @code{break-visibility} overrides
+to both the @code{Clef} and the @code{OctavateEight} layout objects
+to fully suppress such clef symbols at the start of each line.
+
+For explicit clef changes, the @code{explicitClefVisibility}
+property controls both the clef symbol and any octavation symbol
+associated with it.
+
+
+@seealso
+Learning Manual:
+@rlearning{Visibility and color of objects}
+
@node Line styles
@subsection Line styles
The information that determines the end-points is computed
on-the-fly for every graphic object, but it is possible to
-override these.
+override these.
@lilypond[relative=2,ragged-right,verbatim,fragment]
e2 \glissando f
left side with @code{left} instead of @code{right}.
If @code{Y} is not set, the value is computed from the vertical
-position of right attachment point of the spanner.
+position of right attachment point of the spanner.
In case of a line break, the values for the span-points are
extended with contents of the @code{left-broken} and
@code{right-broken} sublists, for example
@lilypond[relative=2,ragged-right,verbatim,fragment]
-\override Glissando #'breakable = ##T
+\override Glissando #'breakable = ##T
\override Glissando #'bound-details #'right-broken #'Y = #-3
c1 \glissando \break
f1
@item X
This is the absolute coordinate of the end point. It is usually
-computed on the fly, and there is little use in overriding it.
+computed on the fly, and there is little use in overriding it.
@item stencil
Line spanners may have symbols at the beginning or end, which is
projects / lilypond.git / commitdiff