How to set properties? Was: rehearsal marks conflict with bar numbers

[Mats Bengtsson]

For years, I have thought of writing a short introduction to the
art of setting properties in LilyPond. Here comes a first attempt.
Feel free to use it as a draft for a section in the manual if you
find it useful.

What You Need to Know About Property Settings
=============================================
=============================================

The default behaviour of LilyPond can be modified by setting
different properties. There are different types of properties
and the syntax is slightly different depending on the type
of property. Also, there are several different ways to set
a property.

Different ways of setting a property
====================================

Here, we describe briefly the syntax for the different methods to
set a property. We show the syntax for setting an object property,
but the same idea applies to context properties, as will be described
below.

* Setting a property that only applies to the next note (or the next 
whatever):

\once \property contextname.objectname \set #'propname = #value
For example, if you want the next note head to be diamond shaped, do
\once \property Voice.NoteHead \set #'style = #'diamond

* Setting a property that applies from now on:

\property contextname.objectname \set #'propname = #value
The 'contextname' describes the scope of the setting. If you say
\property Score..., then the settings applies to all contexts of
the score, if you say \property Staff..., then it applies to the
current Staff context and all contexts within it (but not to other
Staff contexts), and so on.
For example, to make all coming slurs in the current stave dashed, do
\property Staff.Slur \set #'dashed = #1

When you use the \set command, the current value will be
overwritten. If, instead, you say
\property contextname.objectname \override #'propname = #value
LilyPond will remember the old value and you can go back
to the previous value by doing
\property contextname.objectname \revert #'propname


* Setting a property that applies to a complete score:

If you want to set a property that applies to a complete score,
then it's often most convenient to set a property in the
\paper{...} definition. For property settings of objects
that are created before the first note, this may also be
the only way (well, see \applycontext below) to set the
property.
\score{
  ...
  \paper{
    ...
    \translator{
      \ScoreContext
      objectname \set #'propname = #value
      ...
    }
  }
}
What happens here, is that you actually change the definition of
how your contexts should behave. The \ScoreContext is an
identifier that contains the default definition of how what a
Score context should do. If you only say \translator{\ScoreContext},
you will tell LilyPond to use exactly this definition as soon as
it creates a Score context. When adding lines in the \translator{...},
you modify this behaviour. (Note that the \ScoreContext identifier
itself will not be changed, though, so if you want to make more
modifications, you have to do them within the same \translator{...}
block.)
All properties of a context are inherited to all contexts created
within it, so setting properties for the \Score context means that
it will be applied also to all other contexts (unless they are
explicitly set differently within the definition of some other
context). So, normally you can do all the settings as described
above, but if you specifically have to do a property setting at
the Voice context level, you could do
\translator{
  \VoiceContext
  ...
}
In the syntax example above, we have placed the \paper{...}
definition within a \score{...}, but if it is placed outside
the \score{...}, it will apply to all subsequent \score{...}
blocks within the file.


* Advanced techniques for property settings:

Normally, a property has to be set before the actual object
it applies to is created. If you know the Scheme programming
language, you can modify an already existing object using
the \applyoutput function. See the documentation of \applyoutput
and the "generic-output-property.ly" example in the Regression
Test document.


Different types of properties
=============================

There are basically three types of properties:
- Music properties
- Context properties
- Object properties

The music objects and music properties are used in the input part
of LilyPond to store the information of the input files. As a
normal user, you will almost never have to fiddle with these directly.

The context properties describe how the different contexts should
work when translating your input to graphical objects in the output
layout.

The object properties describe exactly how each graphical object
should be typeset.

Above, we described how to set object properties. The syntax for
setting context properties is very similar:
\property contextname.propname = #value
For example, to set the instrument name of the current stave, do
\property Staff.instrument = #"Clarinet"
and to tell LilyPond to print a key signature every time
time the clef is changed in the current PianoStaff context, do
\property PianoStaff.createKeyOnClefChange = ##t

If you want to make a setting that applies to a complete score,
you can also make the setting in the paper section:
\score{
  ...
  \paper{
    ...
    \translator{
      \PianoStaffContext
      createKeyOnClefChange = ##t
      ...
    }
  }
}


How to find out what property to set?
=====================================

See
http://lilypond.org/doc/v2.0/Documentation/user/out-www/lilypond/Constructing-a-tweak.html


Why all these # and ' in the syntax?
====================================

This part of the syntax is taken directly from the Scheme language.
See 
http://lilypond.org/doc/v2.0/Documentation/user/out-www/lilypond/Setting-variables.html


Enjoy!

   /Mats

Graham Percival wrote:
> On Mon, 06 Oct 2003 01:40:46 -0700
> Paul Scott <address@hidden> wrote:
>
> > Graham Percival wrote:
> >
> > > \translator{ \ScoreContext RehearsalMark \override #'padding = #1.5 }
> > >
> > > That's if you stick it in the \paper{} section.  You need to change it
> > > if you want to do that within the \notes{} section.
> >
> > Where do I read about how to do that?  I can't seem to get that 
> > translator to work with other translators.
>
>
> I learned about it from the mailing list and the "tips and tricks" section.
> I'm not certain if it's introduced in the manual (although there are a few
> examples that use it).
>
> Yes, it probably _should_ be introduced in the manual; it's on my big list
> of "things I'd like to add".
>
>
> > to change local padding, etc. for various objects.  The internals helped 
> > find the properties after I figured out it is now called Program 
> > reference. <cid:part1.04070002.00000404@ultrasw.com>
> > Any suggestions as to where to read?  Is there an inheritance diagram or 
> > some source code I can look at to see how the objects are related?
>
>
> I don't know of any complete diagram, but many objects say "Grob Foo is a
> member of the Bar class, and can contain Oof and Rab grobs".
>
> HTH,
> - Graham
>
>
> _______________________________________________
> Lilypond-user mailing list
> address@hidden
> http://mail.gnu.org/mailman/listinfo/lilypond-user

--
=============================================
        Mats Bengtsson
        Signal Processing
        Signals, Sensors and Systems
        Royal Institute of Technology
        SE-100 44  STOCKHOLM
        Sweden
        Phone: (+46) 8 790 8463                         
        Fax:   (+46) 8 790 7260
        Email: address@hidden
        WWW: http://www.s3.kth.se/~mabe
=============================================