GNU LilyPond

Welcome to the home of the GNU Music Typesetter

Node:Setting grob properties, Next:Grob interfaces, Previous:Callbacks, Up:Grobs

Setting grob properties

Grob properties are stored as GUILE association lists, with symbols as keys. In GUILE you can access these using functions described in Section Grob Scheme functions. From C++, grob properties can be accessed using these functions:

  SCM  get_grob_property (SCM) const;
  void set_grob_property (const char * , SCM val);
  void set_immutable_grob_property (const char * , SCM val);
  void set_immutable_grob_property (SCM key, SCM val);
  void set_grob_property (SCM , SCM val);
  void set_grob_pointer (const char*, SCM val);
  SCM  remove_grob_property (const char* nm);

All lookup functions identify undefined properties with end-of-list (i.e. '() in Scheme or SCM_EOL in C)

Properties are stored in two ways:

• mutable properties. Grob properties that change from object to object. The storage of these are private to a grob. For example pointers to other grobs are always stored in the mutable properties.
• immutable properties. Grob properties that are shared across different grobs of the same type. The storage is shared, and hence it is read-only. Typically, this is used to store function callbacks, and default settings. They are initially read from scm/grob-description.scm.

You can change immutable grob properties with the \override syntax:

        \property Voice.Stem \override #'direction = #1

This will push the entry '(direction . 1) on the immutable property list for stems, in effect overriding the setting from scm/grob-description.scm. This can be undone by

        \property Voice.stem \revert #'direction

There is also a shorthand,

        \property Context.GrobType \set #'prop = #VAL

this does a \revert followed by a \override

You can change mutable properties with \outputproperty. This construct looks like

        \context ContextName \outputproperty pred #sym = #val

In this case, in every grob that satisfies pred, the grob property sym is set to val. For example

        \outputproperty
                #(lambda (gr) (string? (ly-get-grob-property gr
                        'text)))
                #'extra-offset = #'(-1.0 . 0.0)

This shifts all grobs that have a text property one staff space to the left. This mechanism is rather clumsy to use, but it allows you tweak any setting of any grob.

Please send GNU LilyPond questions and comments to lilypond-user@gnu.org.

Please send comments on these web pages to lilypond@packages.debian.org

Copyright (c) 1997--2001 Han-Wen Nienhuys and Jan Nieuwenhuizen.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.