@menu
* Visibility and color of objects::
* Size of objects::
+* Length and thickness of objects::
@end menu
@node Visibility and color of objects
This is still not quite right. The note heads and flags are
smaller, but the stems are too long in proportion and the
staff lines are spaced too widely apart. These need to be
-scaled down in proportion to the font reduction.
+scaled down in proportion to the font reduction. The next
+sub-section discusses how this is done.
+@node Length and thickness of objects
+@subsection Length and thickness of objects
+
+@cindex Distances
+@cindex Thickness
+@cindex Length
@cindex magstep
@cindex size, changing
@cindex stem length, changing
@cindex staff line spacing, changing
+Distances and lengths in LilyPond are generally measured in
+staff-spaces, the distance between adjacent lines in the staff,
+(or occasionally half staff spaces) while most @code{thickness}
+properties are measured in units of an internal property called
+@code{line-thickness.} For example, by default, the lines of
+hairpins are given a thickness of 1 unit of @code{line-thickness},
+while the @code{thickness} of a note stem is 1.3. Note, though,
+that some thickness properties are different; for example, the
+thickness of beams is measured in staff-spaces.
+
+So how are lengths to be scaled in proportion to the font size?
This can be done with the help of a special function called
@code{magstep} provided for exactly this purpose. It takes
one argument, the change in font size (#-2 in the example above)
\override Clef #'stencil = ##f
\override TimeSignature #'stencil = ##f
fontSize = #-2
- % Reduce stems and line spacing to match
+ % Reduce stem length and line spacing to match
\override StaffSymbol #'staff-space = #(magstep -2)
}
{ f8 f c }
are always calculated relative to the
value of the @code{staff-space} property these are automatically
scaled down in length too. Note that this affects only the
-vertical scale of the ossia -- the horizontal scale is determined
+vertical scale of the ossia -- the horizontal scale is determined
by the layout of the main music in order to remain synchronised
with it, so it is not affected by any of these changes in size.
Of course, if the scale of all the main music were changed in this
way then the horizontal spacing would be affected. This is
discussed later in the layout section.
-This, then, completes the creation of an ossia. The sizes of all
-other objects may be modified in analogous ways.
+This, then, completes the creation of an ossia. The sizes and
+lengths of all other objects may be modified in analogous ways.
+
+For small changes in scale, as in the example above, the
+thickness of the various drawn lines such as bar lines,
+beams, hairpins, slurs, etc does not usually require global
+adjustment. If the thickness of any particular layout object
+needs to be adjusted this can be best achieved by overriding its
+@code{thickness} property. An example of changing the thickness
+of slurs was shown above in @ref{Properties of layout objects}.
+The thickness of all drawn objects (i.e., those not produced
+from a font) may be changed in the same way.
+
@node Placement of objects
@section Placement of objects
these are usually fixed by the music itself -- they are
vertically positioned on specific lines of the staff or are
tied to other objects that are so positioned. Collisions of
- note heads, stems and accidentals in closely set chords are
+note heads, stems and accidentals in closely set chords are
normally avoided automatically. There are commands and
overrides which can modify this automatic behaviour, as we
shall shortly see.
@subsection Outside staff objects
Outside-staff objects are automatically placed to avoid collisions.
-Objects with the lower value of @code{outside-staff-priority}
+Objects with the lower value of the @code{outside-staff-priority}
property are placed nearer to the staff, and other outside-staff
objects are then raised as far as necessary to avoid collisions.
The @code{outside-staff-priority} is defined in the
@code{grob-interface} and so is a property of all layout objects.
-It is set to @code{#f} (the default) for all within-staff objects,
-and is set explicitly to the default numerical value appropriate
-to the each object as it is created. The following table shows
+By default it is set to @code{#f} for all within-staff objects,
+and to a numerical value appropriate to each outside-staff object
+when the object is created. The following table shows
the default numerical values for some of the commonest
-outside-staff objects. Others may be found in the object
-properties listed in the IR.
-
-TODO Distinguish between Staff and Score objects when it
-is clear how to do this
+outside-staff objects which are, by default, placed in the
+@code{Staff} Context.
@multitable @columnfractions .3 .3
@headitem Layout Object @tab Priority
-@item @code{BarNumber} @tab @code{ 100}
@item @code{DynamicLineSpanner} @tab @code{ 250}
@item @code{DynamicText} @tab @code{ 250}
-@item @code{MetronomeMark} @tab @code{1000}
@item @code{OttavaBracket} @tab @code{ 400}
-@item @code{RehearsalMark} @tab @code{1500}
@item @code{TextScript} @tab @code{ 450}
@item @code{TextSpanner} @tab @code{ 350}
@end multitable
Here is an example showing the default placement of these.
@cindex text spanner
+@funindex \startTextSpan
+@funindex \stopTextSpan
@cindex ottava bracket
@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
c\pp
% Add Dynamic Line Spanner
c\<
-% Add Metronome Mark
-\tempo 4 = 72
% Add Text Script
c^Text
c c
c, c c c
@end lilypond
-This example also shows how to create Text Spanners --
+This example also shows how to create Text Spanners --
text with extender lines above a section of music. The
spanner extends from the @code{\startTextSpan} command to
the @code{\stopTextSpan} command, and the format of the
It also shows how ottava brackets are created.
-Note that bar numbers and rehearsal marks are not shown.
-By default these are created in the @code{Score} context
-and their @code{outside-staff-priority} is ignored
-relative to the rest of these layout objects, which are
-created in the @code{Staff} context.
-If you wish to place bar numbers or rehearsal marks
-in accordance with the value of their
-@code{outside-staff-priority} the @code{Bar_number_engraver}
-or @code{Mark_engraver} should be removed
-from the @code{Score} context and placed in the top
-@code{Staff} context.
-
-If this ordering does not give you the placing you want, the
-priority of the objects may be overridden. Suppose we would
+Note that bar numbers, metronome marks and rehearsal marks
+are not shown. By default these are created in the
+@code{Score} context and their @code{outside-staff-priority}
+is ignored relative to the layout objects which are created
+in the @code{Staff} context.
+If you wish to place bar numbers, metronome marks or rehearsal
+marks in accordance with the value of their
+@code{outside-staff-priority} the @code{Bar_number_engraver},
+@code{Metronome_mark_engraver} or @code{Mark_engraver} respectively
+should be removed from the @code{Score} context and placed in the
+top @code{Staff} context. If this is done, these marks will be
+given the following default @code{outside-staff-priority} values:
+
+@multitable @columnfractions .3 .3
+@headitem Layout Object @tab Priority
+@item @code{BarNumber} @tab @code{ 100}
+@item @code{MetronomeMark} @tab @code{1000}
+@item @code{RehearsalMark} @tab @code{1500}
+@end multitable
+
+If the default values of @code{outside-staff-priority} does not
+give you the placing you want, the priority of any of the objects
+may be overridden. Suppose we would
+like the ottava bracket to be placed below the text spanner in the
+example above. All we need to do is to look up the priority of
+@code{OttavaBracket} in the IR or in the tables above, and reduce
+it to a value lower than that of a @code{TextSpanner}:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+% Set details for later Text Spanner
+\override TextSpanner #'bound-details #'left #'text
+ = \markup { \small \bold Slower }
+% Place dynamics above staff
+\dynamicUp
+%Place following Ottava Bracket below Text Spanners
+\once \override OttavaBracket #'outside-staff-priority = #340
+% Start Ottava Bracket
+#(set-octavation 1)
+c' \startTextSpan
+% Add Dynamic Text
+c\pp
+% Add Dynamic Line Spanner
+c\<
+% Add Text Script
+c^Text
+c c
+% Add Dynamic Text
+c\ff c \stopTextSpan
+% Stop Ottava Bracket
+#(set-octavation 0)
+c, c c c
+@end lilypond
+
+Changing the @code{outside-staff-priority} can also be used to
+control the vertical placement of individual objects, although
+the results may not always be desirable. Suppose we would
like @qq{Text3} to be placed above @qq{Text4} in the example
under Automatic behaviour, above (see @ref{Automatic behaviour}).
All we need to do is to look up the priority of @code{TextScript}
-in the IR or in the table above, and increase the priority of
+in the IR or in the tables above, and increase the priority of
@qq{Text3} to a higher value:
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
This certainly lifts @qq{Text3} above @qq{Text4} but it also
lifts it above @qq{Text2}, and @qq{Text4} now drops down.
-Perhaps this is not so good. Can we instead position them all
-at the same distance from the staff? To do this, we clearly
+Perhaps this is not so good. What we would really like to do
+is to position all the annotation at the same distance above
+the staff? To do this, we clearly
will need to space the notes out horizontally to make more
room for the text. This is done using the @code{fatText}
command.
By default, text produced by markup takes up no horizontal space
as far as laying out the music is concerned. The @code{\fatText}
-command reverses this behaviour, causing the notes to be spaced
+command reverses this behaviour, causing the notes to be spaced
out as far as is necessary to accommodate the text:
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
These properties are to be found in the @code{AccidentalPlacement}
object which, note, lives in the @strong{staff} context. Because
accidentals are always positioned after and to the left of
- note heads only the @code{right-padding} property has any effect.
+note heads only the @code{right-padding} property has any effect.
The @code{staff-padding} property is closely related to the
@code{padding} property: @code{padding}
@cindex left-padding property
@cindex right-padding property
-TODO Example of this - at the moment I can't find one! -td
+TODO Example showing the utility of these properties -td
@subheading staff-padding property
@cindex staff-padding property
@end itemize
-TODO Mention line-thickness somewhere else and move this there
-
-@cindex Tweaks, distances
-@cindex Distances
-
-Distances in LilyPond are measured in staff-spaces, while most
-thickness properties are measured in line-thickness. Some
-properties are different; for example, the thickness of beams
-are measured in staff-spaces. For more information, see the
-relevant portion of the program reference.
-
-
@node Further tweaking
@section Further tweaking
@itemize
-@item
-Setting the @code{transparent} property will cause an object to be printed
-in @q{invisible ink}: the object is not printed, but all its other
-behavior is retained. The object still takes up space, it takes part in
-collisions, and slurs, ties, and beams can be attached to it.
-
-@cindex transparent objects
+@cindex transparent property
+@cindex objects, making invisible
@cindex removing objects
+@cindex objects, removing
@cindex hiding objects
@cindex invisible objects
+
+@item
+Setting the @code{transparent} property will cause an object
+to be printed in @q{invisible ink}: the object is not printed,
+but all its other behavior is retained. The object still takes
+up space, it takes part in collisions, and slurs, ties, and beams
+can be attached to it.
+
The following example demonstrates how to connect different voices
using ties. Normally, ties only connect two notes in the same
voice. By introducing a tie in a different voice,
} >>
@end lilypond
+@cindex stencil property
+
+@item
+For outside-staff objects it is usually better to override the
+object's @code{stencil} property rather than its @code{transparent}
+property when you wish to remove it from the printed output.
+Setting the @code{stencil} property of an object to @code{#f} will
+remove that object entirely from the printed output. This means it
+has no effect on the placement of other objects placed relative to
+it.
+
+For example, if we wished to change the metronome setting in order
+to simulate a fermata in the MIDI output we would not want the
+metronome marking to appear in the printed output, and we would
+not want it to influence the spacing between the two systems or
+the spacing of the notes on the staff. So setting its
+@code{stencil} property to @code{#f} would be the best way.
+We show here the effect of the two methods:
+
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ % Visible tempo marking
+ \tempo 4=120
+ a4 a a
+ \once \override Score.MetronomeMark #'transparent = ##t
+ % Invisible tempo marking to lengthen fermata note in MIDI
+ \tempo 4=80
+ a\fermata
+ \once \override Score.MetronomeMark #'stencil = ##f
+ % Invisible tempo marking to restore tempo in MIDI
+ \tempo 4=120
+ a a a a
+ }
+ \midi { }
+}
+@end lilypond
+
+@noindent
+Both methods remove the metronome mark from the printed output,
+and both affect the MIDI timing as required, but the first
+(transparent) metronome mark still influences the note spacing
+while the second (with no stencil) does not.
+
@end itemize
+
projects / lilypond.git / commitdiff