@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
but is also included with the LilyPond documentation package.
+@c TODO The following is at variance to what actually follows. Fix -td
+
There are four areas where the default settings may be changed:
@itemize
@menu
-* Navigating the program reference::
-* Layout interfaces::
-* Determining the grob property::
-* Naming conventions::
+* Navigating the program reference::
+* Layout interfaces::
+* Determining the grob property::
+* Naming conventions::
@end menu
@node Navigating the program reference
@subsection Naming conventions
Another thing that is needed, is an overview of the various naming
-conventions:
+conventions:
scheme functions: lowercase-with-hyphens (incl. one-word
names)
@section Modifying properties
@menu
-* Overview of modifying properties::
-* The \set command::
-* The \override command::
-* \set versus \override::
-* Objects connected to the input::
+* Overview of modifying properties::
+* The \set command::
+* The \override command::
+* \set versus \override::
+* Objects connected to the input::
@end menu
@node Painting objects white
@unnumberedsubsubsec Painting objects white
+@cindex objects, coloring
+@cindex coloring objects
+@cindex layers
+@cindex printing order
+@cindex overwriting objects
+@cindex objects, overwriting
+@cindex grobs, overwriting
+
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?
+if the object crosses other objects the color of the crossing
+points will be determined by the order in which they are drawn,
+and this may leave a ghostly image of the white object, as shown
+here:
@lilypond[quote,verbatim,relative=2]
-a1 a
-\once \override Score.BarLine #'color = #white
-a a
+\override Staff.Clef #'color = #white
+a1
@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
- }
-}
+All layout objects have a @code{layer} property which should be set
+to an integer. Objects with the lowest value of @code{layer} are
+drawn first, then objects with progressively higher values are drawn,
+so objects with higher values overwrite objects with lower values.
+By default most objects are assigned a @code{layer} value of
+@code{1}, although a few objects, including @code{StaffSymbol} and
+@code{BarLine}, are assigned a value of @code{0}. The order of
+printing objects with the same value of @code{layer} is indeterminate.
+
+In the example above the white clef, with a default @code{layer}
+value of @code{1}, is drawn after the staff lines (default
+@code{layer} value @code{0}), so overwriting them. To change this,
+the @code{Clef} object must be given in a lower value of
+@code{layer}, say @code{-1}, so that it is drawn earlier:
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.Clef #'color = #white
+\override Staff.Clef #'layer = #-1
+a1
@end lilypond
@node Using break-visibility
@unnumberedsubsubsec Using break-visibility
+@c TODO Add making other objects breakable
+
@cindex break-visibility
Most layout objects are printed only once, but some like
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.
+property, which is explained in
+@c Leave this ref on a newline - formats incorrectly otherwise -td
+@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
+@multitable @columnfractions .40 .15 .1 .1 .1
@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
@node Rotating objects
@subsection Rotating objects
-@c FIXME Write this section
+Both layout objects and elements of markup text can be rotated by
+any angle about any point, but the method of doing so differs.
+
+@menu
+* Rotating layout objects::
+* Rotating markup::
+@end menu
+
+@node Rotating layout objects
+@unnumberedsubsubsec Rotating layout objects
+
+@cindex rotating objects
+@cindex objects, rotating
+
+All layout objects which support the @code{grob-interface} can be
+rotated by setting their @code{rotation} property. This takes a
+list of three items: the angle of rotation counter-clockwise,
+and the x and y coordinates of the point relative to the object's
+reference point about which the rotation is to be performed. The
+angle of rotation is specified in degrees and the coordinates in
+staff-spaces.
+
+The angle of rotation and the coordinates of the rotation point must
+be determined by trial and error.
+
+@cindex hairpins, angled
+@cindex angled hairpins
+
+There are only a few situations where the rotation of layout
+objects is useful; the following example shows one situation where
+they may be:
+
+@lilypond[quote,verbatim,relative=1]
+g4\< e' d' f\!
+\override Hairpin #'rotation = #'(20 -1 0)
+g,,4\< e' d' f\!
+@end lilypond
+
+@node Rotating markup
+@unnumberedsubsubsec Rotating markup
+
+All markup text can be rotated to lie at any angle by prefixing it
+with the @code{\rotate} command. The command takes two arguments:
+the angle of rotation in degrees counter-clockwise and the text to
+be rotated. The extents of the text are not rotated: they take
+their values from the extremes of the x and y coordinates of the
+rotated text. In the following example the
+@code{outside-staff-priority} property for text is set to @code{#f}
+to disable the automatic collision avoidance, which would push some
+of the text too high.
+
+@lilypond[quote,verbatim,relative=1]
+\override TextScript #'outside-staff-priority = ##f
+g4^\markup { \rotate #30 "a G" }
+b^\markup { \rotate #30 "a B" }
+des^\markup { \rotate #30 "a D-Flat" }
+fis^\markup { \rotate #30 "an F-Sharp" }
+@end lilypond
+
@node Aligning objects
@subsection Aligning objects
* Vertical grouping of grobs::
* Modifying ends of spanners::
* Modifying stencils::
+* Modifying shapes::
@end menu
@c FIXME Write this section
+@node Modifying shapes
+@subsection Modifying shapes
+
+@c FIXME Write this section
+@c Discussion of Bezier curves and the control-points property
@node Discussion of specific tweaks
@section Discussion of specific tweaks
projects / lilypond.git / blobdiff