From: Trevor Daniels <t.daniels@treda.co.uk>
Date: Tue, 5 Aug 2008 21:46:08 +0000 (+0100)
Subject: GDP NR 5.5.1 Controlling visibility of objects
X-Git-Tag: release/2.11.55-2~3
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=a91a13052a334d531834ca02e8a47aa845333867;p=lilypond.git

GDP NR 5.5.1 Controlling visibility of objects
First draft
---

diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index bdbd53ef22..00f8dbc814 100644
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -1743,13 +1743,351 @@ restricted to a sub-set of the spanners.
 
 @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
@@ -1787,7 +2125,7 @@ d,2 \glissando d'2
 
 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
@@ -1803,14 +2141,14 @@ right end point.  Of course, it is also possible to adjust the
 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
@@ -1835,7 +2173,7 @@ head it is attached to.
 
 @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