Node:Tuning objects, Next:, Up:Tuning output



Tuning objects

The definition of an object is a list of default object properties. For example, the definition of the Stem object (available in scm/define-grobs.scm), includes the following definitions for Stem:

             (thickness . 1.3)
             (beamed-lengths . (0.0 2.5 2.0 1.5))
             (Y-extent-callback . ,Stem::height)
             ...
     

Adding variables on top of this existing definition overrides the system default, and alters the resulting appearance of the layout object.

Syntax

Changing a variable for only one object is commonly achieved with \once:

     \once \property context.objectname
       \override symbol = value
     
Here symbol is a Scheme expression of symbol type, context and objectname is a string and value is a Scheme expression. This command applies a setting only during one moment in the score.

In the following example, only one Stem object is changed from its original setting:

       c4
       \once \property Voice.Stem \set #'thickness = #4
       c4
       c4
     

[picture of music]

For changing more objects, the same command, without \once can be used:

     \property context.objectname \override symbol = value
     
This command adds symbol = value to the definition of objectname in the context context, and this definition stays in place until it is removed.

An existing definition may be removed by the following command:

     \property context.objectname \revert symbol
     
All \override and \revert commands should be balanced. The \set shorthand performs a revert followed by an override, and is often more convenient to use
     \property context.objectname \set symbol = value
     

Some examples:

     c'4 \property Voice.Stem \override #'thickness = #4.0
     c'4
     c'4 \property Voice.Stem \revert #'thickness
     c'4
     

[picture of music]

The following example gives exactly the same result as the previous one (assuming the system default for stem thickness is 1.3):

       c'4 \property Voice.Stem \set #'thickness = #4.0
       c'4
       c'4 \property Voice.Stem \set #'thickness = #1.3
       c'4
     

[picture of music]

Reverting a setting which was not set in the first place has no effect. However, if the setting was set as a system default, this may remove the default value, and this may give surprising results, including crashes. In other words, \override and \revert must be carefully balanced. The following are examples of correct nesting of \override, \set, \revert:

The object description is an Scheme association list. Since a Scheme list is a singly linked list, we can treat it as a stack, and \override and \revert are push and pop operations. The association list is stored in a normal context property, hence

      \property Voice.NoteHead  = #'()
     
will effectively erase NoteHeads from the current Voice. Typically, this will blank the object. However, this mechanism should not be used: it may cause crashes or other anomalous behavior.

See also

OverrideProperty, RevertProperty, PropertySet, All-backend-properties, and All-layout-objects.

Bugs

The backend is not very strict in type-checking object properties. Cyclic references in Scheme values for properties cause hangs and/or crashes. Reverting properties that are system defaults may also lead to crashes.


This page is for LilyPond-2.0.0 (stable-branch).

Report errors to <bug-lilypond@gnu.org>.