@node Objects and interfaces
@subsection Objects and interfaces
-@cindex Objects
-@cindex Grobs
-@cindex Spanners
-@cindex Interfaces
+@cindex objects
+@cindex grobs
+@cindex spanners
+@cindex interfaces
Tweaking involves modifying the internal operation and structures
of the LilyPond program, so we must first introduce some terms
operations these common actions and properties are grouped
together in an object called a @code{grob-interface}. There
are many other groupings of common properties like this, each
-one given a name ending in @code{-interface}. In total there
+one given a name ending in @code{interface}. In total there
are over 100 such interfaces. We shall see later why this is
of interest and use to the user.
@node Tweaking methods
@subsection Tweaking methods
-@itemize
-@item @strong{override command}
+@strong{\override command}
@cindex override command
@funindex \override
used to change the properties of @strong{contexts} and to remove
and add @strong{engravers}, in
@ref{Modifying context properties} and @ref{Adding
-and removing engravers}. We now must meet one more important
-command.
+and removing engravers}. We now must meet some more important
+commands.
The command to change the properties of @strong{layout objects} is
@code{\override}. Because this command has to modify
The general syntax of this command is:
@example
-\override @emph{context}.@emph{layout_object} #'@emph{layout_property} = #@emph{value}
+\override @emph{context}.@emph{layout_object}
+ #'@emph{layout_property} = #@emph{value}
@end example
@noindent
@code{Lyrics}, and we shall omit it in many of the following
examples. We shall see later when it must be specified.
+Later sections deal comprehensively with properties and their
+values, but to illustrate the format and use of these commands
+we shall use just a few simple properties and values which are
+easily understood.
+
For now, don't worry about the @code{#'}, which must precede the
layout property, and the @code{#}, which must precede the value.
These must always be present in exactly this form. This is the
most common command used in tweaking, and most of the rest of
this chapter will be directed to presenting examples of how it is
-used.
+used. Here is a simple example to change the color of the
+note head:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+c d
+\override NoteHead #'color = #red
+e f g
+\override NoteHead #'color = #green
+a b c
+@end lilypond
+
+@strong{\revert command}
+
+@cindex revert command
+@funindex \revert
Once overridden, the property retains its new value until it is
overridden again or a @code{\revert} command is encountered.
Again, just like @emph{context} in the @code{\override} command,
@emph{context} is often not needed. It will be omitted
-in many of the following examples.
+in many of the following examples. Here we revert the color
+of the note head to the default value for the final two notes:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+c d
+\override NoteHead #'color = #red
+e f g
+\override NoteHead #'color = #green
+a
+\revert NoteHead #'color
+b c
+@end lilypond
+
+@strong{\once prefix}
-@item @strong{overrideProperty command}
+Both the @code{\override} and the @code{\set} commands may be
+prefixed by @code{\once}. This causes the following
+@code{\override} or @code{\set} command to be effective only
+during the current musical moment before the property reverts
+back to its default value. Using the same example, we can
+change the color of a single note like this:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+c d
+\once \override NoteHead #'color = #red
+e f g
+\once \override NoteHead #'color = #green
+a b c
+@end lilypond
+
+@strong{\overrideProperty command}
@cindex overrideProperty command
@funindex \overrideProperty
@ruser{Difficult tweaks}.
@c Maybe explain in a later iteration -td
-@item @strong{tweak command}
+@strong{\tweak command}
@cindex tweak command
@funindex \tweak
occur at the same musical moment, such as the notes within a
chord. Using @code{\override} would affect all the notes
within a chord, whereas @code{\tweak} affects just the following
-item in the input stream.
+item in the input stream.
-Here's an example. Suppose we wish to change the size of the
+Here's an example. Suppose we wish to change the size of the
middle note (the E) in a C major chord. Let's first see what
@code{\once \override} would do:
@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
<c e g>4
\once \override NoteHead #'font-size = #-3
- <c e g>4
+ <c e g>
+ <c e g>
@end lilypond
We see the override affects @emph{all} the notes in the chord.
it is effective only on objects which are created directly from
the input stream, essentially note heads and articulations.
(Objects such as stems and accidentals are created later and
-cannot be tweaked in this way). Furthermore, when it is applied
-to note heads these must be within a chord, i.e., within single
-angle brackets, so to tweak a single note the @code{\tweak}
+cannot be tweaked in this way). Furthermore, when it is applied
+to note heads these @emph{must} be within a chord, i.e., within
+single angle brackets, so to tweak a single note the @code{\tweak}
command must be placed inside single angle brackets with the
note.
<c \tweak #'font-size #-3 e g>4
@end lilypond
-Just one in a series of articulations can be modified with
-@code{\tweak}, as shown here:
+Note that the syntax of @code{\tweak} is different from that
+of the @code{\override} command. Neither the context nor the
+layout object should be specified; in fact, it would generate
+an error to do so. These are both implied by the following
+item in the input stream. So the general syntax of the
+@code{\tweak} command is simply:
+
+@example
+\tweak #'@emph{layout_property} = #@emph{value}
+@end example
+
+A @code{\tweak} command can also be used to modify just one in
+a series of articulations, as shown here:
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
a ^Black
Note that the @code{\tweak} command must be preceded by an
articulation mark as if it were an articulation itself.
+@cindex tuplets, nested
+@cindex triplets, nested
+@cindex bracket, tuplet
+@cindex tuplet bracket
+@cindex triplet bracket
+@funindex TupletBracket
+
+The @code{\tweak} command must also be used to change the
+appearance of one of a set of nested tuplets which begin at the
+same musical moment. In the following example, the long tuplet
+bracket and the first of the three short brackets begin at the
+same musical moment, so any @code{\override} command would apply
+to both of them. In the example, @code{\tweak} is used to
+distinguish between them. The first @code{\tweak} command
+specifies that the long tuplet bracket is to be placed above the
+notes and the second one specifies that the tuplet number is to be
+printed in red on the first short tuplet bracket.
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\tweak #'direction #up
+\times 4/3 {
+ \tweak #'color #red
+ \times 2/3 { c8[ c8 c8] }
+ \times 2/3 { c8[ c8 c8] }
+ \times 2/3 { c8[ c8 c8] }
+}
+@end lilypond
+
You can find more details of the @code{\tweak} command in
@ruser{Objects connected to the input}.
-@end itemize
+If nested tuplets do not begin at the same moment their
+appearance may be modified in the usual way with
+@code{\override} commands:
+
+@c NOTE Tuplet brackets collide if notes are high on staff
+@c See issue 509
+@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
+\times 2/3 { c8[ c c]}
+\once \override TupletNumber
+ #'text = #tuplet-number::calc-fraction-text
+\times 2/3 {
+ c[ c]
+ c[ c]
+ \once \override TupletNumber #'transparent = ##t
+ \times 2/3 { c8[ c c] }
+\times 2/3 { c8[ c c]}
+}
+@end lilypond
@node The Internals Reference manual
at first, so we can be sure the command is working. We get:
@example
- \override Slur #'thickness = #5.0
+\override Slur #'thickness = #5.0
@end example
Don't forget the @code{#'} preceding the
@noindent
Now only the first slur is made heavier.
-The @code{\once} command can also be used before @code{\set}
-and @code{\unset}, and before the command to be introduced
-in the following section -- @code{revert}.
-
+The @code{\once} command can also be used before the @code{\set}
+command.
+
@subheading Reverting
@cindex revert
in italics should be
@example
- \override LyricText #'font-shape = #'italic
+\override LyricText #'font-shape = #'italic
@end example
@noindent
@noindent
and the lyrics are all printed in italics.
-@subheading Specifying context in lyric mode
+@subheading Specifying the context in lyric mode
@cindex context, specifying in lyric mode
In the case of lyrics, if you try specifying the context in the
the interpreter cannot recognise them. So the command should be:
@example
- \override Lyrics . LyricText #'font-shape = #'italic
+\override Lyrics . LyricText #'font-shape = #'italic
@end example
@warning{In lyrics always leave whitespace between the final
<b? bes>
@end lilypond
-None work, with the second two showing a bad collision between
+None work, with the second two showing bad collisions between
the two signs.
One way of achieving this is to override the accidental stencil
looking at the internal LilyPond files. To explore these, first
find the directory appropriate to your system, as follows:
-@itemize
-
-@item
-@subheading Linux
+@strong{Linux}
Navigate to
@file{@var{installdir}/lilypond/usr/share/lilypond/current/}
-@item
-@subheading OSX
+@strong{OSX}
Navigate to
@file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}
Terminal, or control-clicking on the LilyPond application and
selecting @q{Show Package Contents}.
-@item
-@subheading Windows
+@strong{Windows}
Using Windows Explorer, navigate to
@file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
-@end itemize
-
Within this directory the two interesting subdirectories are
@itemize
-
@item @file{../ly/ } - contains files in LilyPond format
-
@item @file{../scm/} - contains files in Scheme format
-
@end itemize
Let's begin by looking at some files in @file{../ly/}.
be redefined easily, just like any other variable, at the
head of your input file.
-The following are the most useful files to be found in
+The following are the most useful files to be found in
@file{../ly/}:
@multitable @columnfractions .4 .6
margins.
To be effective under all circumstances these checks must be enabled
-by placing the overrides in a Score @code{\with} block, rather than
+by placing the overrides in a Score @code{\with} block, rather than
in-line in music, as follows:
-@verbatim
-\new Score \with {
+@example
+\new Score \with @{
% Makes sure text scripts and lyrics are within the paper margins
\override PaperColumn #'keep-inside-line = ##t
\override NonMusicalPaperColumn #'keep-inside-line = ##t
-} {
+@} @{
..
-}
-@end verbatim
+@}
+@end example
@node Advanced tweaks with Scheme
@subsection Advanced tweaks with Scheme
-Although many things are possible with the @code{\override} and
-@code{\tweak} commands, an even more powerful way of modifying
-the action of LilyPond is available through a programmable
-interface to the LilyPond internal operation. Functions are
-provided which enable the user to incorporate Scheme code directly
-in the internal operation of LilyPond. For example, it is
-possible to parametrize an override command which is used often
-but with different values.
-
-As the use of these functions require code to be written in the
-Scheme programming language, at least a basic knowledge of
-programming in Scheme is required. An introduction to this is
-provided in the @ref{Scheme tutorial}, and examples showing the
-use of these programmable interfaces can be found in
-@ref{Tweaking with Scheme}.
+Although many things are possible with the @code{\override} and
+@code{\tweak} commands, an even more powerful way of modifying
+the action of LilyPond is available through a programmable
+interface to the LilyPond internal operation. Code written in
+the Scheme programming language can be incorporated directly in
+the internal operation of LilyPond. Of course, at least a basic
+knowledge of programming in Scheme is required to do this, and an
+introduction is provided in the @ref{Scheme tutorial}.
+
+As an illustration of one of the many possibilities, instead of
+setting a property to a constant it can be set to a Scheme
+procedure which is then called whenever that property is accessed
+by LilyPond. The property can then be set dynamically to a value
+determined by the procedure at the time it is called. In this
+example we color the note head in accordance with its position on
+the staff.
+
+@lilypond[quote,verbatim,ragged-right]
+#(define (color-notehead grob)
+ "Color the notehead according to its position on the staff."
+ (let ((mod-position (modulo (ly:grob-property grob 'staff-position) 7)))
+ (case mod-position
+ ;; Return rainbow colors
+ ((1) (x11-color 'red )) ; for C
+ ((2) (x11-color 'orange )) ; for D
+ ((3) (x11-color 'yellow )) ; for E
+ ((4) (x11-color 'green )) ; for F
+ ((5) (x11-color 'blue )) ; for G
+ ((6) (x11-color 'purple )) ; for A
+ ((0) (x11-color 'violet )) ; for B
+ )
+ )
+)
+
+\relative c' {
+ % Arrange to obtain color from color-notehead procedure
+ \override NoteHead #'color = #color-notehead
+ c2 c' |
+ b4 g8 a b4 c |
+ c,2 a' |
+ g1 |
+}
+\addlyrics {
+ Some -- where o -- ver the Rain -- bow way up high,
+}
+@end lilypond
+
+Further examples showing the use of these programmable interfaces
+can be found in @ref{Tweaking with Scheme}.
+
projects / lilypond.git / blobdiff