release: 1.3.42

[lilypond.git] / Documentation / user / properties.itely

@node Properties, , , Reference Manual

Properties are Scheme values, so they have a type.  The type of a
property is listed in parentheses after the property name.

@macro propertytype{t}
 (\t\)
@end macro

@table @samp
  @item @code{Generic_property_list}
    Defines names and types for generic properties. These are properties
    than can be plugged into the backend directly. See the init file
    @file{generic-property.scm} for details.  For internal use only.

  @item @code{XXXVerticalExtent}@indexcode{groupVerticalExtent} @propertytype{Interval: a cons of numbers}
    Hard code the size of the vertical group in context XXX, example
@example
\property Staff.StaffVerticalExtent = #(-5.0 . 5.0)
@end example
    The value is a cons of real numbers, that measure the extent in
    staff spaces.
@end table   

@subsubheading Lyrics properties

@cindex properties!Lyrics

@table @samp
  @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
    Set the font for lyrics.  The available font choices are
    @code{roman}, @code{italic}, @code{bold}, @code{large}, @code{Large},
    @code{typewriter}, and @code{finger}.  The @code{finger} font can
    only display numbers.  Note also that you must be careful when
    using @code{\property} in Lyrics mode, because of the way strings
    are parsed.  Either put quotes around the arguments to
    @code{\property} or be sure to leave a space on both sides of the
    dot.
@end table

@subsubheading Thread properties

@cindex properties!Thread

@table @samp
  @item @code{noteheadStyle}@indexcode{noteheadStyle} @propertytype{string}
    Selects type of note head.  Choices are @code{cross},
    @code{diamond}, @code{harmonic}, @code{transparent}, and @code{""}. 
    They are shown in that order below.

    @mudela[center,verbatim]
      \score {
        \notes { 
          \property Staff.barNonAuto = 1
          \property Voice.noteHeadStyle = cross 
          a'
          \property Voice.noteHeadStyle = diamond
          a'
          \property Voice.noteHeadStyle = harmonic
          a'
          \property Voice.noteHeadStyle = transparent
          a' 
          \property Voice.noteHeadStyle = ""
          a'
        }
        \paper {
          linewidth = -1.;
        }
      }
    
@end mudela
@end table

@subsubheading Grace properties

@cindex properties!Grace

 
@table @samp  
  @item @code{stemStyle}@indexcode{flagStyle} @propertytype{string}
    By default set to @code{"grace"} meaning that all unbeamed 
    notes with flags are typeset with a slash through the flag. 
    Setting to @code{""} gives standard flags.

@mudela[verbatim]
c'8 \property Voice.flagStyle = "grace" c'8
@end mudela
@end table


@subsubheading Voice properties

@cindex properties!Voice

@table @samp  
  @item @code{abbrev}@indexcode{abbrev} @propertytype{integer}
    Set length for tremolo to be used if no length is explicitly
    specified. 

  @item @code{articulationScriptPadding}@indexcode{articulationScriptPadding}
    Determines the extra space added between articulation marks, such
    as staccato, tenuto, trill, up/down bow or fermata, and the
    closest staff line or note.

  @item @code{articulationScriptVerticalDirection} @propertytype{direction}
    @indexcode{articulationScriptVerticalDirection}  
    Determines the location of articulation marks.  Set to @code{\up}
    to print marks above the staff; set to @code{\down} to print marks
    below the staff.  This property does not override explicit
    directions marked with `@code{^}' or `@code{_}' in the mudela file.
    
  @item @code{noAutoBeaming}@indexcode{beamAuto}  @propertytype{boolean}
    If set to 1 then beams are not generated automatically.

  @item @code{beamAutoEnd}@indexcode{beamAutoEnd}  @propertytype{?}
    Specifies when automatically generated beams can end.  See
    section XREF-autobeam [FIXME].

  @item @code{beamAutoBegin}@indexcode{beamAutoBegin}  @propertytype{?}
    Specifies when automatically generated beams can start.  See
    section XREF-autobeam [FIXME].


[outdated FIXME]
  @item @code{beamQuantisation}@indexcode{beamQuantisation} @propertytype{symbol}
    Set to @code{\none} for no quantization.  Set to @code{\normal} to
    quantize position and slope.  Set to @code{\traditional} to avoid
    wedges.  These three settings are available via
    @code{\beamposfree}@keyindex{beamposfree},
    @code{\beamposnormal}@keyindex{beamposnormal}, and
    @code{\beampostraditional}@keyindex{beampostraditional}.

  @item @code{beamSlopeDamping}@indexcode{beamSlopeDamping} @propertytype{number}
    Set to @code{\none} for undamped beams.  Set to @code{\normal} for
    damped beams.  Set to @code{\infinity} for beams with zero slope. 
    The identifiers
    @code{\beamslopeproportional}@keyindex{beamslopeproportional},
    @code{\beamslopedamped}@keyindex{beamslopedamped}, and
    @code{\beamslopezero}@keyindex{beamslopezero} each set the
    corresponding value.

  @item @code{dynamicDirection}@indexcode{dynamicDirection} @propertytype{direction}
    Determines location of dynamic marks.  Set to @code{\up} to print
    marks above the staff; set to @code{\down} to print marks below
    the staff.

  @item @code{dynamicStyle}@indexcode{dynamicStyle} @propertytype{string}
    Set the text style for dynamics.

  @item @code{fontSize}@indexcode{fontSize} @propertytype{number}
    Can be used to select smaller font sizes for music.  The normal
    font size is 0, and the two smaller sizes are -1
    and -2.

@mudela[verbatim]
c''16 \property Staff.fontSize = -2 c''16
@end mudela

   @item @code{forceHorizontalShift}@indexcode{forceHorizontalShift}  
    Force horizontal shift for collision resolution.  It overrides
    automatic collision resolution.  The value is the shift amount
    expressed in @code{note_width}, as set in the paper section.

@item @code{collisionMergeDotted}@indexcode{collisionMergeDotted} @propertytype{boolean}

Merge noteheads in collisions, even if they have a different number of
dots. This normal notation for polyphonic guitar music.

@mudelafile[verbatim]{force-hshift.ly}


[FIXME: this should be moved]

Lilypond always arranges note heads on alternate sides of a stem (that
is, within a single voice) as necessary to prevent collisions (note head
overlaps).  For up stems, the upper note of a colliding pair is placed
on the right side of the stem, the lower on the left. For down stems,
the algorithm works in reverse.
  
Lily also attempts to prevent collisions of note heads in different
voices. A situation where chords of two or more voices are played
simultaneously within one staff.

By default, if only two voices (and both have opposite stem directions)
are in this 'collision group', the notes both are shifted by @code{0.5
\quartwidth} if there are unisons or seconds between the voices.

If there are more than two voices in a collision group, shifting is
inactive by default, since in this case, there are multiple chords with
the same stem direction. By  distinguish between those chords, LilyPond
can do collision resolution in these cases as well.  

Distinguishing between voices with the same stem direction, is done by
setting the property @code{Voice.horizontalNoteShift}.  It must be set
to a different integer for each voice. Then, all note heads in collision
groups (not just unisons and seconds) will be offset, one voice relative
another.  The following fragment of sheet music shows how shifting is
done, with values of @code{horizontalNoteShift} printed over and under
the notes. In this case the chords are just simple notes.

@c URG : mudela book bug.
@mudela[singleline,verbatim]
\score {
        \notes \context Staff <
                \context Voice  = VA { \stemup f''4^"0" }
                \context Voice  = VB {\stemup
                \property Voice.horizontalNoteShift = 1 d''4^" 1" }
                \context Voice  = VC { \stemup \property
Voice.horizontalNoteShift = 2 b'4^"  2" }
                \context Voice  = VD { \stemdown \property
Voice.horizontalNoteShift = 1 g'4_"1 " }
                \context Voice  = VE { \stemdown e'4_"0" }
        >
}
@end mudela

If you are not satisfied with the collision resolution of LilyPond, you
can override the horizontal shift value of the chord of one Voice, by
setting @code{forceHorizontalShift}.  This sets the amount shift,
measured in black note head widths.

To take complete control of note position shifts in complex passages,
you have set things up for normal collisions and override all shifts by
setting @code{forceHorizontalShift} to zero everywhere
@example
\property Voice.horizontalNoteShift = <n>
\property Voice.forceHorizontalShift = "0.0"
@end example

Then you can set the force property to a suitable value before each note
that really needs it (unisons and seconds), and reset it to 0.0 after
the note.  

  @item @code{horizontalNoteShift}@indexcode{horizontalNoteShift}  @propertytype{integer}
    Enable LilyPond to shift notes horizontally if they collide with
    other notes.  This is useful when typesetting many voices on one
    staff.  The identifier @code{\shift}@keyindex{shift} is defined to
    enable this.  Traditionally, the outer chords (the upmost and
    downmost voices), should have no @code{horizontalNoteShift}.

  @item @code{markScriptPadding}@indexcode{markScriptPadding}  @propertytype{number}
    Determines the extra space added between the mark and the closest
    staff line or note.

  @item @code{markDirection}@indexcode{markDirection} @propertytype{direction}
    Determines if marks should be printed above or below the staff.
    Set to @code{\up} to print marks above the staff; set to
    @code{\down} to print marks below the staff.

  @item @code{midiInstrument}@indexcode{midiInstrument} @propertytype{string}
    Sets the instrument for MIDI output.  If this property is not set
    then LilyPond will use the @code{instrument} property.  This must
    be set to one of the strings on the list of MIDI instruments that
    appears in section XREF-midilist [FIXME].  If you use a string which
    is not listed, LilyPond will silently substitute piano.

  @item @code{restStyle}@indexcode{restStyle} @propertytype{string}
    Change the layout of rests shorter than quarter notes. 
    Currently, the standard layout @code{""} and mensural notation
    @code{"mensural"} are available. Mensural rests of duration
    32 or shorter are not available.
@mudela[verbatim]
r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128 
\property Staff.restStyle = "mensural"
r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128 
@end mudela

  @item @code{scriptHorizontal}@indexcode{scriptHorizontal} @propertytype{boolean}
    Put scripts left or right of note heads.  Support for this is
    limited.  Accidentals will collide with scripts.
    
  @item @code{slurVerticalDirection}@indexcode{slurVerticalDirection} @propertytype{direction}
    Set to @code{\free} for free choice of slur direction, set to
    @code{\up} to force slurs up, set to @code{\down} to force slurs
    down.  The shorthands @code{\slurup}@keyindex{slurup},
    @code{\slurdown}@keyindex{slurdown}, and
    @code{\slurboth}@keyindex{slurboth} are available.

  @item @code{slurDash}@indexcode{slurDash} @propertytype{number}
    Set to NIL for normal slurs, 1 for dotted slurs, and a
    larger value for dashed slurs.  Identifiers
    @code{\slurnormal}@keyindex{slurnormal} and
    @code{\slurdotted}@keyindex{slurdotted} are predefined to set the
    first two settings.

@mudela[verbatim]
                c4( )d
                \property Voice.slurDash = 3
                c ( )e
@end mudela             

@item @code{stemLength}@indexcode{stemLength}  
    Set length of stems.  Unit is `@code{interline}/2', so
    @code{stemLength} defaults to 7.
@mudela[verbatim]
g''4 \property Voice.stemLength = #14  g4 \property Voice.stemLength = #3 g4  g,,4  
@end mudela

  @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount} @propertytype{integer}
    Specify the number of beams to draw on the left side of the next
    note.  Overrides automatic beaming.  The value is only used once,
    and then it is erased.

  @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount} @propertytype{integer}
    Specify the number of beams to draw on the right side of the next
    note.  Overrides automatic beaming.  The value is only used once,
    and then it is erased.

  @item @code{tieDash}@indexcode{tieDash} @propertytype{integer}
    Set dashing of ties. See also @code{slurDash}

  @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection} @propertytype{direction}
    Set to @code{\free} for free choice of tie direction, set to
    @code{\up} to force ties up, set to @code{\down} to force ties
    down.

  @item @code{transposing}@indexcode{transposing} @propertytype{integer}
    Transpose the MIDI output.  Set this property to the number of
    half-steps to transpose by.

  @item @code{textEmptyDimension}@indexcode{textEmptyDimension} @propertytype{boolean}
    If set to true then text placed above or below the staff is
    assumed to have zero width.  @code{fatText} and @code{emptyText}
are predefined settings.

@mudela[verbatim]
c4^"foo"  \emptyText c4^"foo" c4
@end mudela

  @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
    Set the text style for superscripts and subscripts.  See above
    for list of text styles.

  @item @code{textScriptPadding}@indexcode{textScriptPadding}  @propertytype{number}
    Determines the extra space added between superscripted resp.
    subscripted text and the closest staff line or note.

  @item @code{verticalDirection}@indexcode{verticalDirection} @propertytype{direction}
    Determines the direction of stems, subscripts, beams, slurs, and
    ties.  Set to @code{\down} to force them down, @code{\up} to force
    them up, or @code{\free} to let LilyPond decide.  This can be used
    to distinguish between voices on the same staff.  The
    @code{\stemdown}@keyindex{stemdown}, @code{\stemup}@keyindex{stemup},
    and @code{\stemboth}@keyindex{stemboth} identifiers set this
    property.
    

  @item @code{tupletDirection}@indexcode{tupletDirection} @propertytype{direction}
    Determines the direction of triplets and other tuplets.  Set to
    @code{\down} to force them below the staff, @code{\up} to force
    them above, or @code{\free} to let LilyPond decide.

  @item  @code{tupletBracketVisibility}@indexcode{tupletBracketVisibility} @propertytype{boolean} or @propertytype{symbol}
  @item @code{tupletNumberVisibility}@indexcode{tupletNumberVisibility} @propertytype{boolean} or @propertytype{symbol}

        These properties the visibility of the tuplet bracket and its
number respectively. Setting it to false will prevent printing of the
associated element. Setting the property to 'if-no-beam will make it
print only if there is no beam associated with this tuplet bracket.

[fixme examples]

  @item @code{tupletInvisible}@indexcode{tupletInvisible} @propertytype{boolean}

    If set to true, tuplet bracket creation is switched off
entirely. This has the same effect as setting both
@code{tupletNumberVisibility} and @code{tupletBracketVisibility} to
@code{#f}, but as this does not even create elements, this setting
uses less memory and time.


@item @code{tupletSpannerDuration} @indexcode{tupletSpannerDuration}
@propertytype{moment}

Normally a tuplet bracket is as wide as the
@code{\times} expression that gave rise to it. By setting this
property, you can make brackets last shorter. Example

@mudela[verbatim,fragment]
\context Voice \times 2/3 {
  \property Voice.tupletSpannerDuration = #(make-moment 1 4)
  [c8 c c] [c c c]
}
@end mudela

@end table

@subsubheading Staff properties

@cindex properties!Staff

@table @samp
 
  @item @code{barNonAuto}@indexcode{barNonAuto} @propertytype{boolean}
    If set to true then bar lines will not be printed
    automatically; they must be explicitly created with @code{\bar}
    keywords.  Unlike with the @code{\cadenza} keyword, measures are
    still counted.  Bar generation will resume according to that
    count if this property is set to zero.

  @item @code{barNumberDirection}@indexcode{barNumberDirection} @propertytype{direction}
    Set to @code{\up} or @code{\down} to put bar numbers above or below
    the staff.

  @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}  
    Sets extra space between the bar number and the bar it labels.

  @item @code{barSize}@indexcode{barSize}  
    Specify the height of the bar lines if it should be different
    than the staff height.
@mudela[verbatim]
c1 c1 \property Staff.barSize = 20 c1 c1 
@end mudela

  @item @code{barAtLineStart}@indexcode{barAtLineStart} @propertytype{boolean}
    Set to true to produce a bar line after the clef at the start
    of each line (but not at the beginning of the music).

        [BROKEN]

  @item @code{clefStyle}@indexcode{clefStyle} @propertytype{string}
    Determines how clefs are typeset.  If set to @code{transparent},
    the clefs are not printed at all, if set to
    @code{fullSizeChanges}, clef changes in the middle of a line are
    typeset with a full size clef.  By default, clef changes are
    typeset in smaller size.

  @item @code{supportedClefTypes}@indexcode{supportedClefTypes} @propertytype{alist}

        Clef settings supported. The value is an association list clef
descriptions indexed by clef name (alto, baritone, etc.).  A clef
description is a list with the glyph name, and the staff position
where it should go. For internal use.

  @item @code{clefPitches}@indexcode{clefPitches} @propertytype{alist}
    Settings for the position of the central C, relative to this clef
    symbol.  For internal use.
   
  @item @code{defaultClef}@indexcode{defaultClef} @propertytype{string}
        Clef setting to use when this context is created.  If unset,
no clef is printed upon creation.

  @item @code{marginDirection}@indexcode{marginDirection} @propertytype{direction}
    Set to @code{\left} or @code{\right} to specify location of
    marginal scripts.

  @item @code{marginScriptPadding}@indexcode{marginScriptPadding}  
    Specify extra space for marginal scripts.

  @item @code{forgetAccidentals}@indexcode{forgetAccidentals} @propertytype{boolean}
    Causes accidentals to be printed at every note instead of
    remembered for the duration of a measure.

  @item @code{noResetKey}@indexcode{noResetKey} @propertytype{boolean}
    Do not reset the key at the start of a measure.  Accidentals will
    be printed only once and are in effect until overridden, possibly
    many measures later.

  @item @code{staffSpace}@indexcode{staffLineLeading}   @propertytype{number}   
    Specifies the distance (in points) between lines of the staff.

  @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines} @propertytype{integer}
    Specifies the number of staff lines.  The default is 5.

  @item @code{postBreakPadding}@indexcode{postBreakPadding}   @propertytype{number}
    Extra space in points to be added after the clef, time signature
    and key signature on the staff.  Deprecated, do not use.

  @item @code{noVoltaBraces}@indexcode{noVoltaBraces} @propertytype{boolean}
    Set to true to suppress the printing of brackets over alternate
    endings specified by the command @code{\alternative}.

 
  @item @code{barAlways}@indexcode{barAlways} @propertytype{boolean}
    If set to true a bar line is drawn after each note.

  @item @code{defaultBarType}@indexcode{defaultBarType} @propertytype{string}
    Sets the default type of bar line. See Section XREF-barlines [FIXME] 
    for a list of available bar types.

  @item @code{instrument}, @code{instr} @propertytype{string}
    @indexcode{instrument}@indexcode{instr}  
    If @code{Staff_margin_engraver}
@cindex Staff_margin_engraver
 is
    added to the Staff translator, then the @code{instrument} property
    is used to label the first line of the staff and the @code{instr}
    property is used to label subsequent lines.  If the
    @code{midiInstrument} property is not set, then @code{instrument}
    is used to determine the instrument for MIDI output.

  @item @code{keyOctaviation}@indexcode{keyOctaviation} @propertytype{boolean}
    If set to false, then keys are the same in all octaves.  If set
    to true then the key signature for different octaves can be
    different and is specified independently:

    @example
      \keysignature bes fis'
    @end example

    The default value is @code{#f}.  Can be set to @code{#t} with
    @code{\specialkey} or reset with @code{\normalkey}.

  @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle} @propertytype{string}
    Changes the default two-digit layout for time signatures.  The
    following values are recognized:

    @table @samp
      @item @code{C}@indexcode{C}  
        4/4 and 2/2 are typeset as C and struck C, respectively.  All
        other time signatures are written with two digits.

      @item @code{old}@indexcode{old}  
        2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
        typeset with old-style mensuration marks.  All other time
        signatures are written with two digits.

      @item @code{1}@indexcode{1}  
        All time signatures are typeset with a single
        digit, e.g. 3/2 is written as 3.

      @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N}, 
      @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
      @code{old6/8alt}@indexcode{old6/8alt}  
        Tells LilyPond to use a specific symbol as time signature.
    @end table

    The different time signature characters are shown below with its
    names:

    @mudela[center,verbatim]

      \score {
        \notes\relative c'' {
          \property Voice.textStyle = typewriter
          \property Staff.timeSignatureStyle = "C2/2"
          \time 2/2; a2^"C2/2" a2 
          \property Staff.timeSignatureStyle = "C4/4"
          \time 2/2; a2^"C4/4" a2 
          \property Staff.timeSignatureStyle = "old2/2"
          \time 2/2; a2^"old2/2" a2 
          \property Staff.timeSignatureStyle = "old3/2"
          \time 2/2; a2^"old3/2" a2 
          \property Staff.timeSignatureStyle = "old2/4"
          \time 2/2; a2^"old2/4" a2 
          \property Staff.timeSignatureStyle = "old4/4"
          \time 2/2; a2^"old4/4" a2 
          \property Staff.timeSignatureStyle = "old6/4"
          \time 2/2; a2^"old6/4" a2 
          \property Staff.timeSignatureStyle = "old9/4"
          \time 2/2; a2^"old9/4" a2 
          \property Staff.timeSignatureStyle = "old4/8"
          \time 2/2; a2^"old4/8" a2 
          \property Staff.timeSignatureStyle = "old6/8"
          \time 2/2; a2^"old6/8" a2 
          \property Staff.timeSignatureStyle = "old6/8alt"
          \time 2/2; a2^"old6/8alt" a2 
          \property Staff.timeSignatureStyle = "old9/8"
          \time 2/2; a2^"old9/8" a2 
        }
        \paper {
          linewidth = 4.5 \in;
        }
      }
    
@end mudela

  @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration} @propertytype{moment}
    Set to an integer to control the size of the brackets printed by
    @code{\alternative}.  The integer specifies the number of whole
    notes duration to use for the brackets.  It is rounded to the
    nearest measure.  This can be used to shrink the length of
    brackets in the situation where one alternative is very large. 
    It may have odd effects if the specified duration is longer than
    the music given in an @code{\alternative}.
@end table
   
@subsubheading GrandStaff properties

@cindex properties!GrandStaff

@table @samp 
  @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign}  @propertytype{number}
    Set the maximum vertical distance between staffs.

  @item @code{minVerticalAlign}@indexcode{minVerticalAlign}  @propertytype{number}
    Set the minimum vertical distance between staffs.  
@end table

@subsubheading Score properties

@cindex properties!Score

@table @samp
  @item @code{skipBars}@indexcode{skipBars} @propertytype{boolean}
    Set to 1 to skip the empty bars that are produced by
    multimeasure notes and rests.  These bars will not appear on the
    printed output.  Set to zero (the default) to expand multimeasure
    notes and rests into their full length, printing the appropriate
    number of empty bars so that synchronization with other voices is
    preserved.

    @quotation

@mudela[fragment,verbatim,center]
r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3

@end mudela
    @end quotation

@item @code{breakAlignOrder}@indexcode{breakAlignOrder} @propertytype{list of string}

   Defines the order in which prefatory matter (clefs, key signatures) appears, eg. this puts the key signatures after the bar lines:
@example
        \property Score.breakAlignOrder = #'(
          "Span_bar"
          "Breathing_sign"
          "Clef_item"
          "Staff_bar"
          "Key_item"
          "Time_signature"
        )
@end example
@end table

@subsubheading ChordNamesVoice properties

@cindex properties!ChordNamesVoice

@table @samp
  @item @code{chordInversion}@indexcode{chordInversion} @propertytype{boolean}
    Determines whether LilyPond should look for chord inversions when
    translating from notes to chord names.  Set to 1 to find
    inversions.  The default is 0 which does not look for
    inversions.
@end table