Documentation/user/properties.itely

   1 @node Properties, , , Reference Manual
   2
   3 Properties are Scheme values, so they have a type.  The type of a
   4 property is listed in parentheses after the property name.
   5
   6 @macro propertytype{t}
   7  (/t/)
   8 @end macro
   9
  10 @cindex properties!Lyrics
  11
  12 @table @samp
  13   @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
  14     Set the font for lyrics.  The available font choices are
  15     @code{roman}, @code{italic}, @code{bold}, @code{large}, @code{Large},
  16     @code{typewriter}, and @code{finger}.  The @code{finger} font can
  17     only display numbers.  Note also that you must be careful when
  18     using @code{\property} in Lyrics mode, because of the way strings
  19     are parsed.  Either put quotes around the arguments to
  20     @code{\property} or be sure to leave a space on both sides of the
  21     dot.
  22 @end table
  23
  24
  25 @cindex properties!Thread
  26
  27 @table @samp
  28   @item @code{noteheadStyle}@indexcode{noteheadStyle} @propertytype{string}
  29     Selects type of note head.  Choices are @code{cross},
  30     @code{diamond}, @code{harmonic}, @code{transparent}, and @code{""}.
  31     They are shown in that order below.
  32
  33     @mudela[center]
  34
  35       \score {
  36         \notes {
  37           \property Staff.barNonAuto = 1
  38           \property Voice.noteHeadStyle = cross
  39           a'
  40           \property Voice.noteHeadStyle = diamond
  41           a'
  42           \property Voice.noteHeadStyle = harmonic
  43           a'
  44           \property Voice.noteHeadStyle = transparent
  45           a'
  46           \property Voice.noteHeadStyle = ""
  47           a'
  48         }
  49         \paper {
  50           linewidth = -1.;
  51         }
  52       }
  53
  54 @end mudela
  55 @end table
  56
  57 @subsubheading Grace properties
  58
  59 @cindex properties!Grace
  60
  61
  62 @table @samp
  63   @item @code{stemStyle}@indexcode{stemStyle} @propertytype{string}
  64     By default set to @code{"grace"} meaning that all unbeamed
  65     notes with flags are typeset with a slash through the flag.
  66     Setting to @code{""} gives standard flags.
  67 @end table
  68
  69
  70 @subsubheading Voice properties
  71
  72 @cindex properties!Voice
  73
  74 @table @samp
  75   @item @code{abbrev}@indexcode{abbrev} @propertytype{integer}
  76     Set length for tremolo to be used if no length is explicitly
  77     specified.
  78
  79   @item @code{articulationScriptPadding}@indexcode{articulationScriptPadding}
  80     Determines the extra space added between articulation marks, such
  81     as staccato, tenuto, trill, up/down bow or fermata, and the
  82     closest staff line or note.
  83
  84   @item @code{articulationScriptVerticalDirection} @propertytype{direction}
  85     @indexcode{articulationScriptVerticalDirection}
  86     Determines the location of articulation marks.  Set to @code{\up}
  87     to print marks above the staff; set to @code{\down} to print marks
  88     below the staff.  This property does not override explicit
  89     directions marked with `@code{^}' or `@code{_}' in the mudela file.
  90
  91   @item @code{noAutoBeaming}@indexcode{beamAuto}
  92     If set to 1 then beams are not generated automatically.
  93
  94   @item @code{beamAutoEnd}@indexcode{beamAutoEnd}
  95     Specifies when automatically generated beams can end.  See
  96     section XREF-autobeam [FIXME].
  97
  98   @item @code{beamAutoBegin}@indexcode{beamAutoBegin}
  99     Specifies when automatically generated beams can start.  See
 100     section XREF-autobeam [FIXME].
 101
 102   @item @code{beamQuantisation}@indexcode{beamQuantisation} @propertytype{symbol}
 103     Set to @code{\none} for no quantization.  Set to @code{\normal} to
 104     quantize position and slope.  Set to @code{\traditional} to avoid
 105     wedges.  These three settings are available via
 106     @code{\beamposfree}@keyindex{beamposfree},
 107     @code{\beamposnormal}@keyindex{beamposnormal}, and
 108     @code{\beampostraditional}@keyindex{beampostraditional}.
 109
 110   @item @code{beamSlopeDamping}@indexcode{beamSlopeDamping} @propertytype{number}
 111     Set to @code{\none} for undamped beams.  Set to @code{\normal} for
 112     damped beams.  Set to @code{\infinity} for beams with zero slope.
 113     The identifiers
 114     @code{\beamslopeproportional}@keyindex{beamslopeproportional},
 115     @code{\beamslopedamped}@keyindex{beamslopedamped}, and
 116     @code{\beamslopezero}@keyindex{beamslopezero} each set the
 117     corresponding value.
 118
 119   @item @code{dynamicDirection}@indexcode{dynamicDirection} @propertytype{direction}
 120     Determines location of dynamic marks.  Set to @code{\up} to print
 121     marks above the staff; set to @code{\down} to print marks below
 122     the staff.
 123
 124   @item @code{dynamicStyle}@indexcode{dynamicStyle} @propertytype{string}
 125     Set the text style for dynamics.
 126
 127   @item @code{fontSize}@indexcode{fontSize} @propertytype{number}
 128     Can be used to select smaller font sizes for music.  The normal
 129     font size is 0, and the two smaller sizes are -1
 130     and -2.
 131
 132    @item @code{forceHorizontalShift}@indexcode{forceHorizontalShift}
 133     Force horizontal shift for collision resolution.  It overrides
 134     automatic collision resolution.  The value is the shift amount
 135     expressed in @code{note_width}, as set in the paper section.
 136
 137 [FIXME: this should be moved]
 138
 139 Lilypond always arranges note heads on alternate sides of a stem (that
 140 is, within a single voice) as necessary to prevent collisions (note head
 141 overlaps).  For up stems, the upper note of a colliding pair is placed
 142 on the right side of the stem, the lower on the left. For down stems,
 143 the algorithm works in reverse.
 144
 145 Lily also attempts to prevent collisions of note heads in different
 146 voices. A situation where chords of two or more voices are played
 147 simultaneously within one staff.
 148
 149 By default, if only two voices (and both have opposite stem directions)
 150 are in this 'collision group', the notes both are shifted by @code{0.5
 151 \quartwidth} if there are unisons or seconds between the voices.
 152
 153 If there are more than two voices in a collision group, shifting is
 154 inactive by default, since in this case, there are multiple chords with
 155 the same stem direction. By  distinguish between those chords, LilyPond
 156 can do collision resolution in these cases as well.
 157
 158 Distinguishing between voices with the same stem direction, is done by
 159 setting the property @code{Voice.horizontalNoteShift}.  It must be set
 160 to a different integer for each voice. Then, all note heads in collision
 161 groups (not just unisons and seconds) will be offset, one voice relative
 162 another.  The following fragment of sheet music shows how shifting is
 163 done, with values of @code{horizontalNoteShift} printed over and under
 164 the notes. In this case the chords are just simple notes.
 165
 166 @c URG : mudela book bug.
 167 @mudela[singleline]
 168 \score {
 169         \notes \context Staff <
 170                 \context Voice  = VA { \stemup f''4^"0" }
 171                 \context Voice  = VB {\stemup
 172                 \property Voice.horizontalNoteShift = 1 d''4^" 1" }
 173                 \context Voice  = VC { \stemup \property
 174 Voice.horizontalNoteShift = 2 b'4^"  2" }
 175                 \context Voice  = VD { \stemdown \property
 176 Voice.horizontalNoteShift = 1 g'4_"1 " }
 177                 \context Voice  = VE { \stemdown e'4_"0" }
 178         >
 179 }
 180 @end mudela
 181
 182 If you are not satisfied with the collision resolution of LilyPond, you
 183 can override the horizontal shift value of the chord of one Voice, by
 184 setting @code{forceHorizontalShift}.  This sets the amount shift,
 185 measured in black note head widths.
 186
 187 To take complete control of note position shifts in complex passages,
 188 you have set things up for normal collisions and override all shifts by
 189 setting @code{forceHorizontalShift} to zero everywhere
 190 @example
 191 \property Voice.horizontalNoteShift = <n>
 192 \property Voice.forceHorizontalShift = "0.0"
 193 @end example
 194
 195 Then you can set the force property to a suitable value before each note
 196 that really needs it (unisons and seconds), and reset it to 0.0 after
 197 the note.
 198
 199   @item @code{horizontalNoteShift}@indexcode{horizontalNoteShift}
 200     Enable LilyPond to shift notes horizontally if they collide with
 201     other notes.  This is useful when typesetting many voices on one
 202     staff.  The identifier @code{\shift}@keyindex{shift} is defined to
 203     enable this.  Traditionally, the outer chords (the upmost and
 204     downmost voices), should have no @code{horizontalNoteShift}.
 205
 206   @item @code{markScriptPadding}@indexcode{markScriptPadding}
 207     Determines the extra space added between the mark and the closest
 208     staff line or note.
 209
 210   @item @code{markDirection}@indexcode{markDirection} @propertytype{direction}
 211     Determines if marks should be printed above or below the staff.
 212     Set to @code{\up} to print marks above the staff; set to
 213     @code{\down} to print marks below the staff.
 214
 215   @item @code{midiInstrument}@indexcode{midiInstrument} @propertytype{string}
 216     Sets the instrument for MIDI output.  If this property is not set
 217     then LilyPond will use the @code{instrument} property.  This must
 218     be set to one of the strings on the list of MIDI instruments that
 219     appears in section XREF-midilist [FIXME].  If you use a string which
 220     is not listed, LilyPond will silently substitute piano.
 221
 222   @item @code{restStyle}@indexcode{restStyle} @propertytype{string}
 223     Change the layout of rests shorter than quarter notes.
 224     Currently, the standard layout @code{""} and mensural notation
 225     @code{"mensural"} are available. Mensural rests of duration
 226     32 or shorter are not available.
 227
 228   @item @code{scriptHorizontal}@indexcode{scriptHorizontal} @propertytype{boolean}
 229     Put scripts left or right of note heads.  Support for this is
 230     limited.  Accidentals will collide with scripts.
 231
 232   @item @code{slurVerticalDirection}@indexcode{slurVerticalDirection} @propertytype{direction}
 233     Set to @code{\free} for free choice of slur direction, set to
 234     @code{\up} to force slurs up, set to @code{\down} to force slurs
 235     down.  The shorthands @code{\slurup}@keyindex{slurup},
 236     @code{\slurdown}@keyindex{slurdown}, and
 237     @code{\slurboth}@keyindex{slurboth} are available.
 238
 239   @item @code{slurDash}@indexcode{slurDash} @propertytype{number}
 240     Set to 0 for normal slurs, 1 for dotted slurs, and a
 241     larger value for dashed slurs.  Identifiers
 242     @code{\slurnormal}@keyindex{slurnormal} and
 243     @code{\slurdotted}@keyindex{slurdotted} are predefined to set the
 244     first two settings.
 245
 246 @item @code{stemLength}@indexcode{stemLength}
 247     Set length of stems.  Unit is `@code{interline}/2', so
 248     @code{stemLength} defaults to 7.
 249
 250   @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount} @propertytype{integer}
 251     Specify the number of beams to draw on the left side of the next
 252     note.  Overrides automatic beaming.  The value is only used once,
 253     and then it is erased.
 254
 255   @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount} @propertytype{integer}
 256     Specify the number of beams to draw on the right side of the next
 257     note.  Overrides automatic beaming.  The value is only used once,
 258     and then it is erased.
 259   @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection} @propertytype{direction}
 260     Set to @code{\free} for free choice of tie direction, set to
 261     @code{\up} to force ties up, set to @code{\down} to force ties
 262     down.
 263
 264   @item @code{transposing}@indexcode{transposing} @propertytype{integer}
 265     Transpose the MIDI output.  Set this property to the number of
 266     half-steps to transpose by.
 267
 268   @item @code{textEmptyDimension}@indexcode{textEmptyDimension} @propertytype{boolean}
 269     If set to 1 then text placed above or below the staff is
 270     assumed to have zero width.
 271
 272   @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
 273     Set the text style for superscripts and subscripts.  See above
 274     for list of text styles.
 275
 276   @item @code{textScriptPadding}@indexcode{textScriptPadding}
 277     Determines the extra space added between superscripted resp.
 278     subscripted text and the closest staff line or note.
 279
 280   @item @code{verticalDirection}@indexcode{verticalDirection} @propertytype{direction}
 281     Determines the direction of stems, subscripts, beams, slurs, and
 282     ties.  Set to @code{\down} to force them down, @code{\up} to force
 283     them up, or @code{\free} to let LilyPond decide.  This can be used
 284     to distinguish between voices on the same staff.  The
 285     @code{\stemdown}@keyindex{stemdown}, @code{\stemup}@keyindex{stemup},
 286     and @code{\stemboth}@keyindex{stemboth} identifiers set this
 287     property.
 288
 289
 290   @item @code{tupletDirection}@indexcode{tupletDirection} @propertytype{direction}
 291     Determines the direction of triplets and other tuplets.  Set to
 292     @code{\down} to force them below the staff, @code{\up} to force
 293     them above, or @code{\free} to let LilyPond decide.
 294
 295   @item @code{tupletVisibility}@indexcode{tupletVisibility}  (number) [FIXME]
 296     Determines whether tuplets of notes are labelled.  Setting
 297     to 0 shows nothing; setting to 1 shows a number;
 298     setting to 2 shows a number and a bracket if there is no
 299     beam; setting to 3 shows a number, and if there is no beam
 300     it adds a bracket; setting to 4 shows both a number and a
 301     bracket unconditionally.
 302
 303 @end table
 304
 305 @subsubheading Staff properties
 306
 307 @cindex properties!Staff
 308
 309 @table @samp
 310
 311   @item @code{barNonAuto}@indexcode{barNonAuto} @propertytype{boolean}
 312     If set to 1 then bar lines will not be printed
 313     automatically; they must be explicitly created with @code{\bar}
 314     keywords.  Unlike with the @code{\cadenza} keyword, measures are
 315     still counted.  Bar generation will resume according to that
 316     count if this property is set to zero.
 317
 318   @item @code{barNumberDirection}@indexcode{barNumberDirection} @propertytype{direction}
 319     Set to @code{\up} or @code{\down} to put bar numbers above or below
 320     the staff.
 321
 322   @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}
 323     Sets extra space between the bar number and the bar it labels.
 324
 325   @item @code{barSize}@indexcode{barSize}
 326     Specify the height of the bar lines if it should be different
 327     than the staff height.
 328
 329   @item @code{barAtLineStart}@indexcode{barAtLineStart} @propertytype{boolean}
 330     Set to 1 to produce a bar line after the clef at the start
 331     of each line (but not at the beginning of the music).
 332
 333   @item @code{clefStyle}@indexcode{clefStyle} @propertytype{string}
 334     Determines how clefs are typeset.  If set to @code{transparent},
 335     the clefs are not printed at all, if set to
 336     @code{fullSizeChanges}, clef changes in the middle of a line are
 337     typeset with a full size clef.  By default, clef changes are
 338     typeset in smaller size.
 339
 340   @item @code{createKeyOnClefChange}@indexcode{createKeyOnClefChange} @propertytype{boolean}
 341     Set to a nonempty string if you want key signatures to be printed
 342     when the clef changes.  Set to the empty string if you do not
 343     want key signatures printed.
 344
 345   @item @code{createInitdefaultClef}@indexcode{createInitdefaultClef} @propertytype{boolean}
 346     Specify whether clefs are created on default? @propertytype{Doesn't seem to
 347     do anything.}
 348
 349   @item @code{defaultClef}@indexcode{defaultClef} @propertytype{string}
 350     Determines the default clef.  See @code{\clef} keyword.
 351
 352   @item @code{marginDirection}@indexcode{marginDirection} @propertytype{direction}
 353     Set to @code{\left} or @code{\right} to specify location of
 354     marginal scripts.
 355
 356   @item @code{marginScriptPadding}@indexcode{marginScriptPadding}
 357     Specify extra space for marginal scripts.
 358
 359   @item @code{forgetAccidentals}@indexcode{forgetAccidentals} @propertytype{boolean}
 360     Causes accidentals to be printed at every note instead of
 361     remembered for the duration of a measure.
 362
 363   @item @code{noResetKey}@indexcode{noResetKey} @propertytype{boolean}
 364     Do not reset the key at the start of a measure.  Accidentals will
 365     be printed only once and are in effect until overridden, possibly
 366     many measures later.
 367
 368   @item @code{staffLineLeading}@indexcode{staffLineLeading}
 369     Specifies the distance (in points) between lines of the staff.
 370
 371   @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines} @propertytype{integer}
 372     Specifies the number of staff lines.  The default is 5.
 373
 374   @item @code{postBreakPadding}@indexcode{postBreakPadding}
 375     Extra space in points to be added after the clef, time signature
 376     and key signature on the staff.  Deprecated, do not use.
 377
 378   @item @code{noVoltaBraces}@indexcode{noVoltaBraces} @propertytype{boolean}
 379     Set to true to suppress the printing of brackets over alternate
 380     endings specified by the command @code{\alternative}.
 381
 382
 383   @item @code{barAlways}@indexcode{barAlways} @propertytype{boolean}
 384     If set to 1 a bar line is drawn after each note.
 385
 386   @item @code{defaultBarType}@indexcode{defaultBarType} @propertytype{string}
 387     Sets the default type of bar line. See Section XREF-barlines [FIXME]
 388     for a list of available bar types.
 389
 390   @item @code{instrument}, @code{instr}
 391     @indexcode{instrument}@indexcode{instr}
 392     If @code{Staff_margin_engraver}
 393 @cindex Staff_margin_engraver
 394  is
 395     added to the Staff translator, then the @code{instrument} property
 396     is used to label the first line of the staff and the @code{instr}
 397     property is used to label subsequent lines.  If the
 398     @code{midiInstrument} property is not set, then @code{instrument}
 399     is used to determine the instrument for MIDI output.
 400
 401   @item @code{keyOctaviation}@indexcode{keyOctaviation} @propertytype{boolean}
 402     If set to 1, then keys are the same in all octaves.  If set
 403     to 0 then the key signature for different octaves can be
 404     different and is specified independently:
 405
 406     @example
 407       \keysignature bes fis'
 408     @end example
 409
 410     The default value is 1.  Can be set to zero with
 411     @code{\specialkey} or reset to 1 with @code{\normalkey}.
 412
 413   @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle} @propertytype{string}
 414     Changes the default two-digit layout for time signatures.  The
 415     following values are recognized:
 416
 417     @table @samp
 418       @item @code{C}@indexcode{C}
 419         4/4 and 2/2 are typeset as C and struck C, respectively.  All
 420         other time signatures are written with two digits.
 421
 422       @item @code{old}@indexcode{old}
 423         2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
 424         typeset with old-style mensuration marks.  All other time
 425         signatures are written with two digits.
 426
 427       @item @code{1}@indexcode{1}
 428         All time signatures are typeset with a single
 429         digit, e.g. 3/2 is written as 3.
 430
 431       @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N},
 432       @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
 433       @code{old6/8alt}@indexcode{old6/8alt}
 434         Tells LilyPond to use a specific symbol as time signature.
 435     @end table
 436
 437     The different time signature characters are shown below with its
 438     names:
 439
 440     @mudela[center]
 441
 442       \score {
 443         \notes\relative c'' {
 444           \property Voice.textStyle = typewriter
 445           \property Staff.timeSignatureStyle = "C2/2"
 446           \time 2/2; a2^"C2/2" a2
 447           \property Staff.timeSignatureStyle = "C4/4"
 448           \time 2/2; a2^"C4/4" a2
 449           \property Staff.timeSignatureStyle = "old2/2"
 450           \time 2/2; a2^"old2/2" a2
 451           \property Staff.timeSignatureStyle = "old3/2"
 452           \time 2/2; a2^"old3/2" a2
 453           \property Staff.timeSignatureStyle = "old2/4"
 454           \time 2/2; a2^"old2/4" a2
 455           \property Staff.timeSignatureStyle = "old4/4"
 456           \time 2/2; a2^"old4/4" a2
 457           \property Staff.timeSignatureStyle = "old6/4"
 458           \time 2/2; a2^"old6/4" a2
 459           \property Staff.timeSignatureStyle = "old9/4"
 460           \time 2/2; a2^"old9/4" a2
 461           \property Staff.timeSignatureStyle = "old4/8"
 462           \time 2/2; a2^"old4/8" a2
 463           \property Staff.timeSignatureStyle = "old6/8"
 464           \time 2/2; a2^"old6/8" a2
 465           \property Staff.timeSignatureStyle = "old6/8alt"
 466           \time 2/2; a2^"old6/8alt" a2
 467           \property Staff.timeSignatureStyle = "old9/8"
 468           \time 2/2; a2^"old9/8" a2
 469         }
 470         \paper {
 471           linewidth = 4.5 \in;
 472         }
 473       }
 474
 475 @end mudela
 476
 477   @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration} @propertytype{moment}
 478     Set to an integer to control the size of the brackets printed by
 479     @code{\alternative}.  The integer specifies the number of whole
 480     notes duration to use for the brackets.  It is rounded to the
 481     nearest measure.  This can be used to shrink the length of
 482     brackets in the situation where one alternative is very large.
 483     It may have odd effects if the specified duration is longer than
 484     the music given in an @code{\alternative}.
 485 @end table
 486
 487
 488 @cindex properties!GrandStaff
 489
 490 @table @samp
 491   @item @code{alignmentReference}@indexcode{alignmentReference}
 492     Set to @code{\center} for vertical alignment reference point to be
 493     in the center of the vertical group.  Set to @code{\up} to put the
 494     reference point at the top of the group.
 495
 496   @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign}
 497     Set the maximum vertical distance between staffs.
 498
 499   @item @code{minVerticalAlign}@indexcode{minVerticalAlign}
 500     Set the minimum vertical distance between staffs.
 501 @end table
 502
 503
 504 @cindex properties!Score
 505
 506 @table @samp
 507   @item @code{skipBars}@indexcode{skipBars} @propertytype{boolean}
 508     Set to 1 to skip the empty bars that are produced by
 509     multimeasure notes and rests.  These bars will not appear on the
 510     printed output.  Set to zero (the default) to expand multimeasure
 511     notes and rests into their full length, printing the appropriate
 512     number of empty bars so that synchronization with other voices is
 513     preserved.
 514
 515     @quotation
 516
 517 @mudela[fragment,verbatim,center]
 518 r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3
 519
 520 @end mudela
 521     @end quotation
 522
 523 @end table
 524
 525
 526 @cindex properties!ChordNamesVoice
 527
 528 @table @samp
 529   @item @code{chordInversion}@indexcode{chordInversion} @propertytype{boolean}
 530     Determines whether LilyPond should look for chord inversions when
 531     translating from notes to chord names.  Set to 1 to find
 532     inversions.  The default is 0 which does not look for
 533     inversions.
 534 @end table
 535