We met some object naming conventions previously, in
@ref{Contexts and engravers}. Here for reference is a list
-of the most common object types together with the conventions
+of the most common object and property types together with
+the conventions
for naming them and a couple of examples of some real names.
@multitable @columnfractions .33 .33 .33
-@headitem Object type
+@headitem Object/property type
@tab Naming convention
@tab Example
@item Contexts, Layout Objects
@emph{layout_object}, which is a member of the @emph{context}
context, to the value @emph{value}.
+The @emph{context} can be omitted in many situations, and in fact
+must be omitted in some.
+@c Eg: Context must not be present when overriding LyricText
+@c properties within a \lyricsto block.
+It can be omitted when the context is one of lowest level
+contexts, i.e., @code{Voice} or @code{Lyrics}, and we shall omit
+it in the following examples. Later we shall see when it must be
+specified.
+
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
\revert @emph{context}.@emph{layout_object} #'@emph{layout_property}
@end example
+Again, the @emph{context} will be omitted for now.
+
There is another form of the override command,
@code{\overrideProperty}, which is occasionally required.
We mention it here for completeness, but for details see
The final tweaking command which is available is @code{\tweak}.
It is not really a new command but a shorthand for an
-@code{\override} command which may be used in a few special
-circumstances. Again, we shall not discuss or
-use it here. You may find the details in
+@code{\override} command which must be used in a few special
+circumstances. Again, we shall not discuss or use it here.
+You may find the details in
@ruser{Objects connected to the input}.
@node The Internals Reference manual
@menu
* Properties of layout objects::
* Properties found in interfaces::
+* Types of properties::
@end menu
@node Properties of layout objects
@cindex layout objects, properties of
Suppose you have a slur in a score which, to your mind,
-appears too thin and you'd like to draw it a little thicker.
+appears too thin and you'd like to draw it a little heavier.
How do you go about doing this? You know from the statements
earlier about the flexibility of LilyPond that such a thing
should be possible, and you would probably guess that an
@code{\override} command would be needed. But is there a
-thickness property for a slur, and if there is, how might it
+heaviness property for a slur, and if there is, how might it
be modified? This is where the Internals Reference manual
comes in. It contains all the information you might need to
construct this and all other @code{\override} commands.
@code{thickness} and that the new value should be a number
somewhat larger than 1.2 if we are to make slurs thicker.
-But what is the Context? We could guess that slurs are in
-the Voice context, as they are clearly closely associated
-with individual lines of music, but can we be sure? To
-find out, go back to the top of the IR page describing the
-Slur, where it says @q{Slur objects are created by: Slur
-engraver}. So slurs will be created in whichever context
-the @code{Slur_engraver} is in. Follow the link to the
-@code{Slur_engraver} page. At the very bottom it tells
-us that @code{Slur_engraver} is part of five Voice contexts,
-including the standard voice context, @code{Voice}, so our
-guess was correct.
-
We can now construct the @code{\override} command by simply
-substituting the values we have found for the names. Let's
-use a very large value for the thickness at first, so we
-can be sure the command is working. We get:
+substituting the values we have found for the names, omitting
+the context. Let's use a very large value for the thickness
+at first, so we can be sure the command is working. We get:
@example
- \override Voice.Slur #'thickness = #5.0
+ \override Slur #'thickness = #5.0
@end example
Don't forget the @code{#'} preceding the
\time 6/8
{
% Increase thickness of all following slurs from 1.2 to 5.0
- \override Voice.Slur #'thickness = #5.0
+ \override Slur #'thickness = #5.0
r4 b8 b[( g]) g | g[( e]) e d[( f]) a | a g
}
\addlyrics { The man who feels love's sweet e -- mo -- tion }
}
@end lilypond
+What if we had needed the Context? What is it? We could
+guess that slurs are in
+the Voice context, as they are clearly closely associated
+with individual lines of music, but can we be sure? To
+find out, go back to the top of the IR page describing the
+Slur, where it says @q{Slur objects are created by: Slur
+engraver}. So slurs will be created in whichever context
+the @code{Slur_engraver} is in. Follow the link to the
+@code{Slur_engraver} page. At the very bottom it tells
+us that @code{Slur_engraver} is part of five Voice contexts,
+including the standard voice context, @code{Voice}, so our
+guess was correct. And because @code{Voice} is one of the
+lowest level contexts we can omit it in this location.
+
+@heading Overriding once only
+
@cindex overriding once only
@cindex once override
@funindex \once
-As you can see, all the slurs are thicker. But, what if we
+As you can see, all the slurs are thicker in the final example
+above. But, what if we
wanted just the first slur to be thicker? This is achieved
with the @code{\once} command. Placed immediately before
the @code{\override} command it causes it to affect only the
{
r4 b8
% Increase thickness of immediately following slur only
- \once \override Voice.Slur #'thickness = #5.0
+ \once \override Slur #'thickness = #5.0
b[( g]) g | g[( e]) e d[( f]) a | a g
}
\addlyrics { The man who feels love's sweet e -- mo -- tion }
}
@end lilypond
+@heading Reverting
+
Finally, what if we wanted just the first two slurs to be
heavier? Well, we could use two commands, each preceded by
@code{\once} placed immediately before each of the notes where
{
r4 b8
% Increase thickness of immediately following slur only
- \once \override Voice.Slur #'thickness = #5.0
+ \once \override Slur #'thickness = #5.0
b[( g]) g |
% Increase thickness of immediately following slur only
- \once \override Voice.Slur #'thickness = #5.0
+ \once \override Slur #'thickness = #5.0
g[( e]) e d[( f]) a | a g
}
\addlyrics { The man who feels love's sweet e -- mo -- tion }
{
r4 b8
% Increase thickness of all following slurs from 1.2 to 5.0
- \override Voice.Slur #'thickness = #5.0
+ \override Slur #'thickness = #5.0
b[( g]) g |
g[( e])
% Revert thickness of all following slurs to default of 1.2
- \revert Voice.Slur #'thickness
+ \revert Slur #'thickness
e d[( f]) a | a g
}
\addlyrics { The man who feels love's sweet e -- mo -- tion }
@cindex interface properties
@cindex properties in interfaces
-Suppose now that we wish to color a slur red. We would go
-to the properties on Slurs in the IR as described in the
-previous section, and look in vain, because there is nothing
-there that looks like it might change the color. This is
-because the color property is one that is common to all
-layout objects, so, rather than including it in every layout
+Suppose now that we wish to print the lyrics in italics. What
+@code{\override} command do we need to do this?
+We first look in the IR page listing @q{All layout objects}, as
+before, and look for an object that might print lyrics. We
+find @code{LyricText}, which looks right. Clicking on this shows
+the settable properties for lyric text. These include the
+@code{font-series} and @code{font-size}, but nothing that might
+give an italic shape.
+This is because the shape property is one that is common to all
+font objects, so, rather than including it in every layout
object, it is grouped together with other similar common
properties and placed in an @strong{Interface}, the
-@code{grob-interface}. (Remember, grob is short for
-@q{graphical object}, itself another name for a layout object.)
+@code{font-interface}.
So now we need to learn how to find the properties of interfaces,
and to discover what objects use these interface properties.
-Look again at the IR page which describes the Slur. At the
+Look again at the IR page which describes LyricText. At the
bottom of the page is a list of clickable (in the html versions
-of the IT) interfaces which the Slur supports. The list has
-three items: @code{spanner-interface}, @code{slur-interface}
-and @code{grob-interface}.
-
-The @code{spanner-interface} holds properties common to
-spanners -- objects which extend over several notes --
-as do Slurs.
-
-The @code{slur-interface} holds properties common to ordinary
-slurs and phrasing slurs.
-
-The @code{grob-interface} holds properties common to all
-layout objects, and it is here that you will find the
-@code{color} property, which appears as
+of the IR) interfaces which LyricText supports. The list has
+seven items, including @code{font-interface}, which looks
+promising. Clicking on this brings up the properties associated
+with this interface, which are also properties of all the objects
+which support it, including LyricText.
+
+Now we see all the user-settable properties which control fonts,
+including @code{font-shape(symbol)}, where @code{symbol} can be
+set to @code{upright}, @code{italics} or @code{caps}.
+
+Let's see if we can now construct the @code{\override} command
+to change the lyrics to italics. The object is @code{LyricText},
+the property is @code{'font-shape} and the value is
+@code{'italic}. As before, we'll omit the context.
+
+As an aside, although it is an important one, note that because
+the values of
+@code{'font-shape} are symbols they must be introduced with a
+single apostrophe, @code{'}. That is why apostrophes
+are needed before @code{'thickness} in the earlier example
+and @code{'font-shape}. These are both symbols too. So
+what are symbols? They are special names which are known
+internally to LilyPond. Some of them are names of properties,
+like @code{'thickness} or @code{'font-shape}, others are in
+effect special values that can be given to properties, like
+@code{'italic}. Note the distinction from arbitary
+text strings, which would appear as @code{"a text string"}.
+
+Ok, so the @code{\override} command we need to print the lyrics
+in italics should be
@example
-color(list)
- The color of this grob
+ \override LyricText #'font-shape = #'italic
@end example
-... to be continued
-
-@ignore
-@c The rest of this section is rubbish and will need to be rewritten -td
-
-The value then is described as a @emph{list}? Why do we need
-a list to specify a color? Well, we don't, but there are
-several ways to specify a color and some of them do need a list.
-See the Notation Reference @ruser{List of colors}. This shows
-the @q{Normal colors} and the longer list of @q{X color names}.
-The normal colors are written as a one-member list, which can
-be written simply as @code{red}. But the X color names must be
-written as a two-member list:
+@noindent
+and this should be placed just in front of and close to the
+lyrics which it should affect, like this:
@example
-(x11-color 'LimeGreen)
+@{
+ \time 6/8
+ @{
+ r4 b8
+ b[( cis]) g |
+ g[( e]) e
+ d[( fis]) a | a g
+ @}
+ \addlyrics @{
+ \override LyricText #'font-shape = #'italic
+ The man who feels love's sweet e -- mo -- tion @}
+@}
@end example
@noindent
-where the first item in the list is always @q{x11-color} to
-indicate this is a color from the longer list of X11 colors,
-and the second item is the name of the color from the list
-of X11 colors in the Notation Reference.
-
-@cindex properties as lists
-@cindex properties as text strings
-
-This introduces two new concepts.
-
-First the brackets round
-this property value are required to form the two items into
-a list, as required by the color property. Brackets would
-generate an error if placed around a @q{normal color}, though,
-because these are shorthand names known to LilyPond which
-generate the appropriate list automatically.
-
-Second, because the second
-item is a text string it needs to be introduced with a
-single apostrophe, @code{'}. This is why these apostrophes
-are needed before @code{'thickness} and @code{'color'}.
-These are both text strings too.
-
-So, putting this into practice, we can change the second
-slur to the normal color magenta and the third slur
-to the X11 color, DarkOrange, where we have made all the
-slurs thicker to show the colors better, as follows:
+and the lyrics are all printed in italics.
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
- \time 6/8
- {
- \override Voice.Slur #'thickness = #5.0
- r4 b8
- b[( g]) g |
- \once \override Voice.Slur #'color = #magenta
- g[( e]) e
- \once \override Voice.Slur #'color = #(x11-color 'DarkOrange)
- d[( f]) a | a g
- }
- \addlyrics { The man who feels love's sweet e -- mo -- tion }
-}
-@end lilypond
+(In this case, if you try specifying the context the command
+will fail. In lyric mode the @code{Lyrics} context is always
+assumed and must not be specified.)
+
+@node Types of properties
+@subsection Types of properties
+
+@cindex Property types
+
+So far we have seen two types of property: @code{number} and
+@code{symbol}. To be valid, the value given to a property
+must be of the correct type and obey the rules for that type.
+The type of property is always shown in brackets after the
+property name in the IR. Here is a list of the types you
+may need, together with the rules for that type, and some
+examples. You must add a hash symbol, @code{#}, of course,
+to the front of these values when they are entered in the
+@code{\override} command.
+
+@multitable @columnfractions .33 .33 .33
+@headitem Property type
+ @tab Rules
+ @tab Examples
+@item Boolean
+ @tab Either True or False, represented by #t or #f
+ @tab #t, #f
+@item Dimension (in staff space)
+ @tab A positive decimal number (in units of staff space)
+ @tab 2.5, 0.34
+@item Direction
+ @tab A valid direction symbol or its numerical equivalent
+ @tab #LEFT, #CENTER, #UP, 1, -1
+@item Integer
+ @tab A positive whole number
+ @tab 3, 1
+@item List
+ @tab A bracketed set of items separated by spaces,
+preceded by an apostrophe
+ @tab '(left-edge staff-bar), '(1), '(1.0 0.25 0.5)
+@item Markup
+ @tab Any valid markup
+ @tab \markup @{ \italic "cresc." @}
+@item Moment
+ @tab A fraction of a whole note constructed with the
+make-moment function
+ @tab (ly:make-moment 1 4), (ly:make-moment 3 8)
+@item Number
+ @tab Any positive or negative decimal value
+ @tab 3.5, -2.45
+@item Pair (of numbers)
+ @tab Two numbers separated by a 'space . space' and enclosed
+in brackets preceded by an apostrophe
+ @tab '(2 . 3.5), '(0.1 . -3.2)
+@item Symbol
+ @tab Any of the set of permitted symbols for that property,
+preceded by an apostrophe
+ @tab 'italic, 'inside
+@item Unknown
+ @tab A procedure or #f (to cause no action)
+ @tab bend::print, ly:text-interface::print, #f
+@item Vector
+ @tab A list of three items enclosed in brackets and preceded
+by a hash, @code{#}, sign
+ @tab #(#t #t #f),
+@end multitable
+
+... to be continued
-@end ignore
-
@c Old stuff follows -td
projects / lilypond.git / commitdiff